Repository: libretro/docs Branch: master Commit: b379d8be6060 Files: 406 Total size: 3.1 MB Directory structure: gitextract_w_m8relu/ ├── .editorconfig ├── .gitattributes ├── .github/ │ ├── CONTRIBUTING.md │ ├── ISSUE_TEMPLATE/ │ │ └── bug_report.md │ ├── ISSUE_TEMPLATE.md │ └── workflows/ │ ├── main.yml │ └── typos.yml ├── .gitignore ├── .travis.yml ├── CNAME ├── LICENSE ├── Makefile ├── README.md ├── _typos.toml ├── archive/ │ ├── libretro-gl.tex │ ├── libretro-shader.lyx │ ├── libretro.lyx │ ├── overlay.tex │ ├── ratecontrol.tex │ ├── retroarch-cores-manual.lyx │ ├── retroarch-enduserguide.lyx │ └── retroarch-manual.lyx ├── deploy ├── dist/ │ └── mkdocs_macros_plugin-0.5.0-py3.9.egg ├── docs/ │ ├── CNAME │ ├── development/ │ │ ├── bounties.md │ │ ├── coding-standards.md │ │ ├── cores/ │ │ │ ├── core-options-translation.md │ │ │ ├── core-specific/ │ │ │ │ ├── dolphin.md │ │ │ │ ├── flycast.md │ │ │ │ ├── ishiiruka.md │ │ │ │ ├── mame-2003-plus.md │ │ │ │ ├── mame-2016.md │ │ │ │ ├── mame.md │ │ │ │ ├── pcsx2.md │ │ │ │ └── swanstation.md │ │ │ ├── developing-cores.md │ │ │ ├── dynamic-rate-control.md │ │ │ └── opengl-cores.md │ │ ├── frontends.md │ │ ├── input-api.md │ │ ├── libretro-overview.md │ │ ├── licenses.md │ │ ├── retroarch/ │ │ │ ├── compilation/ │ │ │ │ ├── 3ds.md │ │ │ │ ├── android.md │ │ │ │ ├── dos.md │ │ │ │ ├── gamecube.md │ │ │ │ ├── haiku.md │ │ │ │ ├── ios.md │ │ │ │ ├── linux-and-bsd.md │ │ │ │ ├── msvc-runtime-versions.md │ │ │ │ ├── osx.md │ │ │ │ ├── ps2.md │ │ │ │ ├── psp.md │ │ │ │ ├── psvita.md │ │ │ │ ├── switch-libnx.md │ │ │ │ ├── ubuntu.md │ │ │ │ ├── wii.md │ │ │ │ ├── wiiu.md │ │ │ │ ├── windows.md │ │ │ │ ├── windows2000-msvc-cmdline.md │ │ │ │ ├── windows2000.md │ │ │ │ ├── windows95-msvc-cmdline.md │ │ │ │ ├── windows98-msvc-cmdline.md │ │ │ │ ├── windows98.md │ │ │ │ ├── windowsNT351-msvc-cmdline.md │ │ │ │ ├── windowsXP-msvc-cmdline.md │ │ │ │ └── windowsXP.md │ │ │ ├── debugging.md │ │ │ ├── glossary.md │ │ │ ├── input/ │ │ │ │ ├── input-drivers.md │ │ │ │ ├── overlay.md │ │ │ │ └── parallel-port-controllers.md │ │ │ ├── netplay.md │ │ │ ├── network-control-interface.md │ │ │ ├── new-menu-options.md │ │ │ ├── new-translations-crowdin.md │ │ │ └── new-translations.md │ │ └── shader/ │ │ ├── cg-shaders.md │ │ ├── content-aware-shaders.md │ │ ├── glsl-shaders.md │ │ ├── shader-lookup-textures.md │ │ ├── shader-overview.md │ │ ├── slang-shaders.md │ │ └── xml-shaders.md │ ├── googlea211139c43d4edca.html │ ├── guides/ │ │ ├── accessibility.md │ │ ├── ai-service.md │ │ ├── arcade-getting-started.md │ │ ├── bios.md │ │ ├── building-lakka.md │ │ ├── building-ludo.md │ │ ├── change-directories.md │ │ ├── cheat-codes.md │ │ ├── cli-intro.md │ │ ├── controller-autoconfiguration.md │ │ ├── core-list.md │ │ ├── crtswitchres.md │ │ ├── databases.md │ │ ├── disc-swapping.md │ │ ├── download-cores.md │ │ ├── file-browser.md │ │ ├── generating-retroarch-logs.md │ │ ├── glui.md │ │ ├── gui.md │ │ ├── import-content.md │ │ ├── input-and-controls.md │ │ ├── input-controller-drivers.md │ │ ├── install-3ds2ds.md │ │ ├── install-android.md │ │ ├── install-facebookportal.md │ │ ├── install-genesismini.md │ │ ├── install-gnu.md │ │ ├── install-ios.md │ │ ├── install-lakka.md │ │ ├── install-libnx.md │ │ ├── install-ludo.md │ │ ├── install-macos.md │ │ ├── install-ps2.md │ │ ├── install-ps3.md │ │ ├── install-psc.md │ │ ├── install-psp.md │ │ ├── install-psv.md │ │ ├── install-steamlink.md │ │ ├── install-windows-2000-me-98SE.md │ │ ├── install-windows.md │ │ ├── kms-mode.md │ │ ├── latency.md │ │ ├── launch-content.md │ │ ├── led-drivers.md │ │ ├── libretro-overlays.md │ │ ├── memorymonitoring.md │ │ ├── navigating.md │ │ ├── netplay-faq.md │ │ ├── netplay-getting-started.md │ │ ├── netplay-multiple-controllers.md │ │ ├── optimal-vsync.md │ │ ├── overlay-pointing-devices.md │ │ ├── overrides.md │ │ ├── ozone.md │ │ ├── ozone.md.backup │ │ ├── quick-menu.md │ │ ├── recording-and-streaming.md │ │ ├── retroachievements.md │ │ ├── retroarch-accessibility-guide.md │ │ ├── retroarch-cloud-sync.md │ │ ├── rgui.md │ │ ├── roms-playlists-thumbnails.md │ │ ├── rpi.md │ │ ├── runahead.md │ │ ├── shaders.md │ │ ├── softpatching.md │ │ ├── softwarelist-getting-started.md │ │ ├── starting-a-game.md │ │ ├── themes.md │ │ ├── troubleshooting-retroarch.md │ │ ├── tv.md │ │ ├── web-player.md │ │ ├── xmb-menu-map.md │ │ └── xmb.md │ ├── image/ │ │ ├── Button_Pack/ │ │ │ ├── Readme.txt │ │ │ └── Vector Source.fla │ │ ├── core/ │ │ │ ├── ffmpeg/ │ │ │ │ └── audio-preview.ogg │ │ │ └── genesis_plus_gx/ │ │ │ └── bram.drawio │ │ └── retroarch/ │ │ └── ozone/ │ │ └── bgm.ogg │ ├── index.md │ ├── library/ │ │ ├── 2048.md │ │ ├── 3d_engine.md │ │ ├── amiarcadia.md │ │ ├── anarch.md │ │ ├── ardens.md │ │ ├── atari800.md │ │ ├── b2.md │ │ ├── beetle_bsnes.md │ │ ├── beetle_cygne.md │ │ ├── beetle_gba.md │ │ ├── beetle_lynx.md │ │ ├── beetle_neopop.md │ │ ├── beetle_pc_fx.md │ │ ├── beetle_pce_fast.md │ │ ├── beetle_psx.md │ │ ├── beetle_psx_hw.md │ │ ├── beetle_saturn.md │ │ ├── beetle_sgx.md │ │ ├── beetle_vb.md │ │ ├── bios.md │ │ ├── bk.md │ │ ├── blastem.md │ │ ├── bluemsx.md │ │ ├── bnes.md │ │ ├── boom3.md │ │ ├── bsnes-jg.md │ │ ├── bsnes_accuracy.md │ │ ├── bsnes_balanced.md │ │ ├── bsnes_cplusplus98.md │ │ ├── bsnes_mercury_accuracy.md │ │ ├── bsnes_mercury_balanced.md │ │ ├── bsnes_mercury_performance.md │ │ ├── bsnes_performance.md │ │ ├── cannonball.md │ │ ├── caprice32.md │ │ ├── chailove.md │ │ ├── citra.md │ │ ├── citra_canary.md │ │ ├── clownmdemu.md │ │ ├── compatibility/ │ │ │ ├── 32x.md │ │ │ ├── 3do.md │ │ │ ├── dc.md │ │ │ ├── ds.md │ │ │ ├── gba.md │ │ │ ├── gbc.md │ │ │ ├── jaguar.md │ │ │ ├── lynx.md │ │ │ ├── nes.md │ │ │ ├── pcfx.md │ │ │ ├── psx.md │ │ │ ├── saturn.md │ │ │ ├── snes.md │ │ │ └── wswan.md │ │ ├── craft.md │ │ ├── crocods.md │ │ ├── desmume.md │ │ ├── desmume_2015.md │ │ ├── dice.md │ │ ├── dinothawr.md │ │ ├── dolphin.md │ │ ├── dosbox.md │ │ ├── dosbox_pure.md │ │ ├── doukutsu-rs.md │ │ ├── dummy.md │ │ ├── easyrpg.md │ │ ├── ecwolf.md │ │ ├── eightyone.md │ │ ├── emuscv.md │ │ ├── emux_chip8.md │ │ ├── emux_gb.md │ │ ├── emux_nes.md │ │ ├── emux_sms.md │ │ ├── ep128emu.md │ │ ├── fbneo.md │ │ ├── fceumm.md │ │ ├── ffmpeg.md │ │ ├── flycast.md │ │ ├── fmsx.md │ │ ├── freeintv.md │ │ ├── fuse.md │ │ ├── gam4980.md │ │ ├── gambatte.md │ │ ├── game_music_emu.md │ │ ├── gearboy.md │ │ ├── gearcoleco.md │ │ ├── geargrafx.md │ │ ├── gearlynx.md │ │ ├── gearsystem.md │ │ ├── genesis_plus_gx.md │ │ ├── geolith.md │ │ ├── gpsp.md │ │ ├── gw.md │ │ ├── handy.md │ │ ├── hatari.md │ │ ├── higan_accuracy.md │ │ ├── holani.md │ │ ├── imageviewer.md │ │ ├── jaxe.md │ │ ├── jollycv.md │ │ ├── jumpnbump.md │ │ ├── kronos.md │ │ ├── lowres_nx.md │ │ ├── lrps2.md │ │ ├── lutro.md │ │ ├── m2000.md │ │ ├── mame2003_plus.md │ │ ├── mame_2003.md │ │ ├── mame_2010.md │ │ ├── melonds.md │ │ ├── melonds_ds.md │ │ ├── mesen-s.md │ │ ├── mesen.md │ │ ├── meteor.md │ │ ├── mgba.md │ │ ├── microw8.md │ │ ├── minivmac.md │ │ ├── mkxp-z.md │ │ ├── mr_boom.md │ │ ├── mu.md │ │ ├── mupen64plus.md │ │ ├── neko_project_ii_kai.md │ │ ├── nestopia.md │ │ ├── nestopia_ue.md │ │ ├── nside_balanced.md │ │ ├── numero.md │ │ ├── nxengine.md │ │ ├── o2em.md │ │ ├── openlara.md │ │ ├── opera.md │ │ ├── pcsx2.md │ │ ├── pcsx_rearmed.md │ │ ├── pd777.md │ │ ├── picodrive.md │ │ ├── play.md │ │ ├── pocketcdg.md │ │ ├── pokemini.md │ │ ├── ppsspp.md │ │ ├── prboom.md │ │ ├── prosystem.md │ │ ├── puae.md │ │ ├── px68k.md │ │ ├── quasi88.md │ │ ├── quicknes.md │ │ ├── race.md │ │ ├── redream.md │ │ ├── reminiscence.md │ │ ├── remote_retropad.md │ │ ├── rvvm.md │ │ ├── same_cdi.md │ │ ├── sameboy.md │ │ ├── sameduck.md │ │ ├── scummvm.md │ │ ├── smsplus.md │ │ ├── snes9x.md │ │ ├── snes9x_2002.md │ │ ├── snes9x_2005.md │ │ ├── snes9x_2005_plus.md │ │ ├── snes9x_2010.md │ │ ├── stella.md │ │ ├── stone_soup.md │ │ ├── tempgba.md │ │ ├── tgb_dual.md │ │ ├── the_powder_toy.md │ │ ├── theodore.md │ │ ├── tic80.md │ │ ├── tyrquake.md │ │ ├── uzem.md │ │ ├── vaporspec.md │ │ ├── vba_m.md │ │ ├── vba_next.md │ │ ├── vecx.md │ │ ├── vemulator.md │ │ ├── vice.md │ │ ├── video_processor.md │ │ ├── vircon32.md │ │ ├── virtual_jaguar.md │ │ ├── virtualxt.md │ │ ├── wasm-4.md │ │ ├── xrick.md │ │ ├── yabasanshiro.md │ │ └── yabause.md │ ├── meta/ │ │ ├── core-template.md │ │ ├── how-to-contribute.md │ │ ├── see-also.md │ │ └── shader-preview-template.md │ ├── overrides/ │ │ ├── home.html │ │ └── main.html │ ├── requirements.txt │ ├── shader/ │ │ ├── 3dfx.md │ │ ├── antialiasing.md │ │ ├── auto-box.md │ │ ├── blurs.md │ │ ├── border.md │ │ ├── cel.md │ │ ├── cgp.md │ │ ├── crt.md │ │ ├── crt_royale.md │ │ ├── cubic.md │ │ ├── ddt.md │ │ ├── dithering.md │ │ ├── eagle.md │ │ ├── handheld-border.md │ │ ├── handheld.md │ │ ├── hqx.md │ │ ├── introduction.md │ │ ├── linear.md │ │ ├── motionblur.md │ │ ├── mudlord.md │ │ ├── nedi.md │ │ ├── nnedi3.md │ │ ├── ntsc.md │ │ ├── presets.md │ │ ├── retro.md │ │ ├── sabr.md │ │ ├── scalefx-old-shaders.md │ │ ├── scalefx.md │ │ ├── scalehq.md │ │ ├── scalenx.md │ │ ├── sharpen.md │ │ ├── windowed.md │ │ ├── xbr.md │ │ ├── xbrz.md │ │ ├── xsal.md │ │ └── xsoft.md │ ├── start/ │ │ ├── installation.md │ │ ├── last-station.md │ │ ├── love-at-first-sight.md │ │ └── understanding.md │ ├── stylesheets/ │ │ └── extra.css │ ├── support/ │ │ ├── privacy-policy.md │ │ └── quick-informations.md │ └── tech/ │ └── developing-cores.md ├── mkdocs.yml ├── mkdocs_macros_plugin.egg-info/ │ ├── PKG-INFO │ ├── SOURCES.txt │ ├── dependency_links.txt │ ├── entry_points.txt │ ├── requires.txt │ └── top_level.txt └── typings/ └── lunr.d.ts ================================================ FILE CONTENTS ================================================ ================================================ FILE: .editorconfig ================================================ # Libretro coding standards # See https://libretro.readthedocs.io/en/latest/development/coding-standards/ # Or search for "Libretro Coding Standards" root = true [*] end_of_line = lf insert_final_newline = true trim_trailing_whitespace = true charset = utf-8 [Makefile] indent_style = space indent_size = 3 [*.{c,h}] indent_style = space indent_size = 3 max_line_length = 80 ================================================ FILE: .gitattributes ================================================ # Set the default behavior, in case people don't have core.autocrlf set. * text=auto # Declare files that will always have LF Unix-style line endings on checkout. *.c text eol=lf *.h text eol=lf *.in text eol=lf *.md text eol=lf *.txt text eol=lf # Denote all files that are truly binary and should not be modified. *.png binary *.jpg binary *.gif binary *.zip binary *.pdf binary ================================================ FILE: .github/CONTRIBUTING.md ================================================ # Contribute to the documentation The docs are written in [Markdown](https://en.wikipedia.org/wiki/Markdown) if you need help with the syntax use [this guide](https://guides.github.com/features/mastering-markdown/).
Mkdocs uses some [Markdown extensions](http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions) that you may have to familiarize with. The documentation source is maintained via [Git](https://en.wikipedia.org/wiki/Git)
For novice users that don't know how to use the command line you can use [Github Desktop](https://desktop.github.com/).
For more info on how to use git [refer to their help](https://help.github.com/) In order to propose improvements to a document: 1. [Clone the repo](https://github.com/libretro/docs) (If you are using [Github Desktop](https://desktop.github.com/), select Clone>Open in Desktop) 2. Make the changes and update your clone 3. Test, [follow the Building section to render the site](https://github.com/libretro/docs/blob/master/README.md#building) 4. Propose your changes using the button "New Pull Request" [in the docs repo](https://github.com/libretro/docs)
make sure that you are comparing **your forks edited branch** to the **docs master branch** There is a To-Do list for libretro/docs [here](https://docs.libretro.com/meta/todo/) You can submit suggestions or issues regarding documentation at the [libretro/docs issue tracker](https://github.com/libretro/docs/issues) or in our [forum thread](https://forums.libretro.com/t/wip-adding-pages-to-documentation-site/10078/). ## Adding a new core These are the documents that should be added/updated when a new core is added to the libretro ecosystem. - Add the core to docs/library/ (Follow the latest core template. docs/meta/core_template.md) - Add the core to mkdocs.yml - Add the core to docs/meta/core_list.md - Add the core to docs/meta/see_also.md if it's related to another core in some way - Add the core to docs/tech/licenses.md - Add the core to docs/meta/todo.md - Add the core to docs/guides/softpatching.md if it supports softpatching - Add the core to docs/guides/retroachievements.md if it supports cheevos ================================================ FILE: .github/ISSUE_TEMPLATE/bug_report.md ================================================ --- name: Bug report about: Create a report to help us improve title: '' labels: bug assignees: '' --- **Describe the bug** A clear and concise description of what the bug is. **Expected behavior/changes** A clear and concise description of what you expected to happen. **Additional context** Add any other context about the problem here. ================================================ FILE: .github/ISSUE_TEMPLATE.md ================================================ # First and foremost consider this: - Only documentation related issues should be filed here. Not RetroArch bugs, or core bugs, or game bugs, or build errors. - Before reporting a 404, refresh the doc a few times. ## Documents [Add a list of documents that should be changed here.] ### Proposed changes [What changes should be done to the documents.] ================================================ FILE: .github/workflows/main.yml ================================================ name: Publish docs via GitHub Pages on: push: branches: - master workflow_dispatch: inputs: logLevel: description: 'Log level' required: true default: 'release' type: choice options: - debug - release - testing jobs: build: name: Deploy docs runs-on: ubuntu-latest steps: - name: Checkout main uses: actions/checkout@v2 - name: Deploy docs uses: mhausenblas/mkdocs-deploy-gh-pages@master env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} CONFIG_FILE: mkdocs.yml EXTRA_PACKAGES: build-base REQUIREMENTS: docs/requirements.txt ================================================ FILE: .github/workflows/typos.yml ================================================ # Spell checker name: Typos Action permissions: contents: read on: pull_request: branches: [master] jobs: spelling: name: Spell Check with Typos runs-on: ubuntu-latest steps: - name: Checkout Actions Repository uses: actions/checkout@v4 - name: Spell Check Repo uses: crate-ci/typos@v1.30.2 ================================================ FILE: .gitignore ================================================ /site .DS_Store .venv ================================================ FILE: .travis.yml ================================================ language: python python: - "3.6" install: - pip install mkdocs - pip install mkdocs-material - pip install pymdown-extensions - pip install pygments script: - mkdocs build ================================================ FILE: CNAME ================================================ docs.libretro.com ================================================ FILE: LICENSE ================================================ MIT License Copyright (c) 2017 libretro Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: Makefile ================================================ MKDOCS_AVAILABLE := $(shell command -v mkdocs 2> /dev/null) build: dependencies @mkdocs build start: dependencies @mkdocs serve install: pip install mkdocs mkdocs-material dependencies: ifndef MKDOCS_AVAILABLE $(error "mkdocs is not available. Use 'make install' to install dependencies.") endif ================================================ FILE: README.md ================================================ # Libretro Docs This repository contains the source for the official Libretro and RetroArch documentation, available at [docs.libretro.com](https://docs.libretro.com/). # Contribute to the documentation These docs are written in [Markdown.](https://en.wikipedia.org/wiki/Markdown) If you need help with the syntax, use [this guide](https://guides.github.com/features/mastering-markdown/). Mkdocs uses some [Markdown extensions](http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions) that you may have to familiarize with. The documentation source is maintained via [Git](https://en.wikipedia.org/wiki/Git). For more info on how to use git, [refer to Github's help page.](https://help.github.com/) In order to propose improvements to a document: 1. [Clone the repo](https://github.com/libretro/docs) 2. Make the changes and update your clone 3. Follow the "Building the docs" section to render the documentation site locally 4. Propose your changes using the button `New Pull Request` [in the docs repo](https://github.com/libretro/docs) There is a To-Do list for libretro/docs *here* and you can submit suggestions or issues regarding documentation at the [libretro/docs issue tracker](https://github.com/libretro/docs/issues). ## Building the docs 1. Make sure you have [Python](https://www.python.org/) and [pip](https://pip.pypa.io) installed ``` python --version pip --version ``` !!! Note "Building in Windows/msys2" If you are using the standard RetroArch msys2 environment, you will need to install python with the command `pacman -S python`. Next you will need to download [the `get-pip.py` script](https://bootstrap.pypa.io/get-pip.py) from the `pip` bootstrap site. Finally, execute the script with the command `python get-pip.py`. 2. Install MkDocs ``` pip install mkdocs ``` 3. Install MkDocs-Material ``` pip install mkdocs-material ``` 4. Install PyMdown Extensions ``` pip install pymdown-extensions ``` 5. Install mkdocs-git-revision-date ``` pip install mkdocs-git-revision-date-plugin ``` 6. Install mkdocs-macros ``` pip install mkdocs-macros-plugin ``` 7. Build the site ``` mkdocs build ``` 8. The documentation will be built to the `site` directory; preview any changes with MkDocs' built-in dev-server before submitting a pull request ``` mkdocs serve ``` **References** - [Guide to installing mkdocs](https://www.mkdocs.org/#installation) ## Adding a new core These are the documents that should be added/updated when a new core is added to the libretro ecosystem. - Add the core to docs/library/ (Follow the latest core template. docs/meta/core-template.md) - Add the core to mkdocs.yml - Add the core to docs/guides/core-list.md - Add the core to docs/meta/see-also.md if it's related to another core in some way - Add the core to docs/development/licenses.md - Add the core to docs/guides/softpatching.md if it supports softpatching - Add the core to docs/guides/retroachievements.md if it supports cheevos - Add the core to docs/library/bios.md if it needs a BIOS ================================================ FILE: _typos.toml ================================================ [files] extend-exclude = [ ".git/", # Version control files "achive/*", # Archive files ] # Match Inside a Word - Case Insensitive [default.extend-words] ue = "ue" # Nestopia UE sav = "sav" # .sav file extension kernal = "kernal" # Commodore's low-level Operating System ================================================ FILE: archive/libretro-gl.tex ================================================ \documentclass[11pt]{article} \author{Hans-Kristian Arntzen} \title{Implementing a Hardware Accelerated Libretro Core} \begin{document} \maketitle \begin{abstract} Libretro API~\footnote{http://libretro.org} recently received support for cores to use OpenGL (GL2+ or GLES2) directly instead of software rendering to a buffer which is subsequently used by the frontend. This article explains how a core can take advantage of this, and which considerations must be taken into account. This article assumes familiarity with the libretro API. Cores which use hardware rendering can still use known frontend features, such as multi-pass shaders. This is accomplished by letting cores render to frame buffer objects (FBOs) instead of the back buffer~\footnote{GL drivers must support render-to-texture extensions for this to work.}. This addition to the libretro API is designed to be used with hardware-accelerated emulator cores, as well as serving as a framework for graphical demos and experiments. \end{abstract} \section*{Application model} Using OpenGL in a libretro context is somewhat different than when you use libraries like SDL, GLFW or SFML. In libretro, the frontend owns the OpenGL context. For an application using conventional libraries like SDL, the application will do this: \begin{itemize} \item Initialize, create a window of specific size \item Initialize OpenGL resources \item Per frame, handle window events (resize), handle input, render as desired, swap buffers \item Tear down context and window \end{itemize} Using libretro API, platform specifics like managing windows, rendering surfaces and input are all handled by the frontend. The core will only deal with rendering to a surface. The core renders to an FBO of fixed size, determined by the core. The frontend takes this rendered data and stretches to screen as desired by the user. It can apply shaders, change aspect ratio, etc. This model is equivalent to software rendering where \texttt{retro\_video\_refresh\_t} callback is called. \section*{Using OpenGL in libretro} \begin{itemize} \item Use \texttt{RETRO\_ENVIRONMENT\_SET\_PIXEL\_FORMAT} and request a 32-bit format. This is the format that the resulting framebuffer will have~\footnote{In reality, RetroArch converts all 16-bit data (\texttt{RETRO\_PIXEL\_FORMAT\_RGB565}) to 32-bit (\texttt{XRGB8888}) when running desktop GL for performance reasons. In GLES mode, this is not done, however. Do not rely on this behavior, and be explicit about it.}. \item Use \texttt{RETRO\_ENVIRONMENT\_SET\_HW\_RENDER} environment callback in \\\texttt{retro\_load\_game()}, notifying frontend that core is using hardware rendering. An OpenGL 2+ or GLES2 context can be specified here. If this is not supported the callback will return false, and you can fallback to software rendering or refuse to start. \item In \texttt{retro\_get\_system\_av\_info()}, as normal, \texttt{max\_width} and \\\texttt{max\_height} fields specify the maximum resolution the core will render to. \item When the frontend has created a context or reset the context, \\\texttt{retro\_hw\_context\_reset\_t} is called. Here, OpenGL resources can be initialized. The frontend can reset the context at will (e.g. when changing from fullscreen to windowed mode and vice versa). The core should take this into account. It will be notified when reinitialization needs to happen. \item A callback to grab OpenGL symbols is exposed via \\\texttt{retro\_hw\_get\_proc\_address\_t}. Use this to retrieve symbols and extensions. \item In \texttt{retro\_run()}, use \texttt{retro\_hw\_get\_current\_framebuffer\_t} callback to get which FBO to render to~\footnote{e.g. \texttt{glBindFramebuffer(GL\_FRAMEBUFFER, get\_current\_framebuffer())}}. This is your "backbuffer". Do not attempt to render to the real back buffer. You must call this every frame as it can change every frame. The dimensions of this FBO are at least as big as declared in \texttt{max\_width} and \texttt{max\_height}. If desired, the FBO also has a depth buffer attached~\footnote{see \texttt{RETRO\_ENVIRONMENT\_SET\_HW\_RENDER}}. \item When done rendering, call \texttt{retro\_video\_refresh\_t} with the macro \texttt{RETRO\_HW\_FRAME\_BUFFER\_VALID} as argument for buffer. Width and height should be specified as well, but pitch argument is irrelevant and will be ignored. If the frame is duped~\footnote{RETRO\_ENVIRONMENT\_CAN\_DUPE}, the buffer argument takes \texttt{NULL} as normal. \end{itemize} \section*{Important considerations in the OpenGL code} The frontend and libretro core share OpenGL context state. Some considerations have to be taken into account for this cooperation to work nicely. \begin{itemize} \item Don't leave buffers and global objects bound when calling \\\texttt{retro\_video\_refresh\_t}. Make sure to unbind everything, i.e. VAOs, VBOs, shader programs, textures, etc. Failing to do this could potentially hit strange bugs. The frontend will also follow this rule to avoid clashes. Being tidy here is considered good practice anyway. \item The GL viewport will be modified by frontend as well as libretro core. Set this every frame. \item \texttt{glEnable()} state like depth testing, etc, is likely to be disabled in frontend as it's just rendering a quad to screen. Enable this per-frame if you use depth testing. There is no need to disable this before calling \\\texttt{retro\_video\_refresh\_t}. \item Avoid VAOs. They tend to break on less-than-stellar drivers~\footnote{At least AMD drivers on Windows are known to break here.}. \item Try to write code which is GLES2 as well as GL2+ (w/ extensions) compliant. This ensures maximum target surface for the libretro core. \item Libretro treats top-left as origin. OpenGL treats bottom-left as origin. To be compatible with the libretro model, top-left semantics are preserved. Rendering normally will cause the image to be flipped vertically. To avoid this, simply scale the final projection matrix by $[1, -1, 1, 1]$. \end{itemize} \section*{Test implementations} A very basic test implementation of libretro GL interface is available in RetroArch repository on GitHub~\footnote{https://github.com/Themaister/RetroArch/tree/master/libretro-test-gl}. It displays two spinning quads. It runs both as a GLES2 and GL2 core depending on \texttt{GLES} environment variable. A slightly more involved test core is found on Bitbucket~\footnote{https://bitbucket.org/Themaister/libretro-gl}. It uses instanced rendering of a textured cube, with FPS-style fly-by camera. It uses libretro's mouse API as well. It is valid GLES and GL2 at the same time. \section*{Building a libretro core} Libretro is an interface, and not a utility library. Libretro cores are built as standalone dynamic or static libraries, and as they use GL symbols here, they must link against GL symbols themselves. An example of how this can be done is shown in the test implementation~\footnote{https://github.com/Themaister/RetroArch/blob/master/libretro-test-gl/Makefile}. \end{document} ================================================ FILE: archive/libretro-shader.lyx ================================================ #LyX 2.0 created this file. For more info see http://www.lyx.org/ \lyxformat 413 \begin_document \begin_header \textclass article \use_default_options true \maintain_unincluded_children false \language english \language_package default \inputencoding auto \fontencoding global \font_roman default \font_sans default \font_typewriter default \font_default_family default \use_non_tex_fonts false \font_sc false \font_osf false \font_sf_scale 100 \font_tt_scale 100 \graphics default \default_output_format default \output_sync 0 \bibtex_command default \index_command default \paperfontsize default \spacing single \use_hyperref true \pdf_title "Cg/HLSL Libretro shader tutorial" \pdf_author "Hans-Kristian Antzen, Daniel De Matteis" \pdf_bookmarks true \pdf_bookmarksnumbered false \pdf_bookmarksopen false \pdf_bookmarksopenlevel 1 \pdf_breaklinks false \pdf_pdfborder false \pdf_colorlinks true \pdf_backref false \pdf_pdfusetitle true \papersize default \use_geometry false \use_amsmath 1 \use_esint 1 \use_mhchem 1 \use_mathdots 1 \cite_engine basic \use_bibtopic false \use_indices false \paperorientation portrait \suppress_date false \use_refstyle 1 \index Index \shortcut idx \color #008000 \end_index \secnumdepth 3 \tocdepth 3 \paragraph_separation indent \paragraph_indentation default \quotes_language english \papercolumns 1 \papersides 1 \paperpagestyle default \tracking_changes false \output_changes false \html_math_output 0 \html_css_as_file 0 \html_be_strict false \end_header \begin_body \begin_layout Title Cg/HLSL libretro shader tutorial \end_layout \begin_layout Author Hans-Kristian Arntzen, Daniel De Matteis \end_layout \begin_layout Standard \begin_inset CommandInset toc LatexCommand tableofcontents \end_inset \end_layout \begin_layout Section Introduction \end_layout \begin_layout Standard This document is for a (fresh) shader developer that wants to develop shader programs for use in various emulators/games. Shader programs run on your GPU, and thus enables very sophisticated effects to be performed on the picture which might not be possible in real-time on the CPU. Some introduction to shader programming in general is given, so more experience d developers that only need reference for the specification may just skip ahead. \end_layout \begin_layout Standard Current emulators that support the specification explained here to a certain degree are: \end_layout \begin_layout Itemize \begin_inset Index idx status open \begin_layout Plain Layout RetroArch \end_layout \end_inset RetroArch \end_layout \begin_layout Itemize \begin_inset Index idx status open \begin_layout Plain Layout SNES9x \end_layout \end_inset SNES9x Win32 \end_layout \begin_layout Standard There are three popular shader languages in use today: \end_layout \begin_layout Itemize \begin_inset Index idx status open \begin_layout Plain Layout HLSL \end_layout \end_inset HLSL (High-Level Shading Language, Direct3D) \end_layout \begin_layout Itemize \begin_inset Index idx status open \begin_layout Plain Layout GLSL \end_layout \end_inset GLSL (GL Shading Language, OpenGL) \end_layout \begin_layout Itemize \begin_inset Index idx status open \begin_layout Plain Layout Cg \end_layout \end_inset Cg (HLSL/GLSL, nVidia) \end_layout \begin_layout Standard The spec is for the \begin_inset Index idx status open \begin_layout Plain Layout Cg \end_layout \end_inset Cg shading language developed by nVidia. It \begin_inset Quotes eld \end_inset wraps \begin_inset Quotes erd \end_inset around \begin_inset Index idx status open \begin_layout Plain Layout OpenGL \end_layout \end_inset OpenGL and \begin_inset Index idx status open \begin_layout Plain Layout HLSL \end_layout \end_inset HLSL to make shaders written in Cg quite portable. It is also the shading language implemented on the \begin_inset Index idx status open \begin_layout Plain Layout PlayStation3 \end_layout \end_inset PlayStation3, thus increasing the popularity of it. \end_layout \begin_layout Subsection The rendering pipeline \end_layout \begin_layout Standard With shaders you are able to take control over a large chunk of the GPUs inner workings by writing your own programs that are uploaded and run on the GPU. In the old days, GPUs were a big black box that was highly configurable using endless amount of API calls. In more modern times, rather than giving you endless amounts of buttons, you are expected to implement the few «buttons» you actually need, and have a streamlined API. \end_layout \begin_layout Standard The rendering pipeline is somewhat complex, but we can in general simplify it to: \end_layout \begin_layout Itemize Vertex processing \end_layout \begin_layout Itemize Rasterization \end_layout \begin_layout Itemize Fragment processing \end_layout \begin_layout Itemize Framebuffer blend \end_layout \begin_layout Standard We are allowed to take control of what happens during vertex processing, and fragment processing. \end_layout \begin_layout Subsection A Cg/HLSL program \end_layout \begin_layout Standard If you were to process an image on a CPU, you would most likely do something like this: \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout for (unsigned y = 0; y < height; y++) { \end_layout \begin_layout Plain Layout for (unsigned x = 0; x < width; x++) \end_layout \begin_layout Plain Layout out_pixel[y][x] = process_pixel(in_pixel[y][x], y, x); \end_layout \begin_layout Plain Layout } \end_layout \end_inset We quickly realize that this is highly serial and slow. We see that out_pixel[y][x] isn't dependent on out_pixel[y + k][x + k], so we see that we can parallelize quite a bit. \end_layout \begin_layout Standard Essentially, we only need to implement process_pixel() as a single function, which is called thousands, even millions of time every frame. The only purpose in life for process_pixel() is to process an input, and produce an output. No state is needed, thus, a \begin_inset Quotes eld \end_inset pure \begin_inset Quotes erd \end_inset function in computer science terms. \end_layout \begin_layout Standard For the Cg program, we need to implement two different functions. \end_layout \begin_layout Standard main_vertex() takes care of transforming every incoming vertex from camera space down to clip space. This essentially means projection of 3D (coordinates on GPU) down to 2D (your screen) \begin_inset Foot status collapsed \begin_layout Plain Layout Since we're dealing with old school emulators here, which are already 2D, the vertex shading is very trivial. \end_layout \end_inset . \end_layout \begin_layout Standard Vertex shaders get various coordinates as input, and uniforms. Every vertex emitted by the emulator is run through main_vertex which calculate s the final output position \begin_inset Foot status collapsed \begin_layout Plain Layout For our emulators this is just 4 times, since we're rendering a quad on the screen. 3D games would obviously have a lot more vertices. \end_layout \end_inset . \end_layout \begin_layout Standard While coordinates differ for each invocation, uniforms are constant throughout every call. Think of it as a global variable that you're not allowed to change. \end_layout \begin_layout Standard Vertex shading can almost be ignored altogether, but since the vertex shader is run only 4 times, and the fragment shader is run millions of times per frame, it is a good idea to precalculate values in vertex shader that can later be used in fragment shader. There are some limitiations to this which will be mentioned later. \end_layout \begin_layout Standard main_fragment() takes care of calculating a pixel color for every single output pixel on the screen. If you're playing at 1080p, the fragment shader will have to be run 1920 * 1080 times! This is obviously straining on the GPU unless the shader is written efficiently. \end_layout \begin_layout Standard Obviously, main_fragment is where the real action happens. For many shaders we can stick with a \begin_inset Quotes eld \end_inset dummy \begin_inset Quotes erd \end_inset vertex shader which does some very simple stuff. \end_layout \begin_layout Standard The fragment shader receives a handle to a texture (the game frame itself), and the texture coordinate for the current pixel, and a bunch of uniforms. \end_layout \begin_layout Standard A fragment shader's final output is a color, simple as that. Processing ends here. \end_layout \begin_layout Section Hello World \end_layout \begin_layout Standard We'll start off with the basic vertex shader. No fancy things are being done. You'll see a similiar vertex shader in most of the Cg programs out there in the wild. \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout void main_vertex( \end_layout \begin_layout Plain Layout float4 pos : POSITION, \end_layout \begin_layout Plain Layout out float4 out_pos : POSITION, \end_layout \begin_layout Plain Layout uniform float4x4 modelViewProj, \end_layout \begin_layout Plain Layout float4 color : COLOR, \end_layout \begin_layout Plain Layout out float4 out_color : COLOR, \end_layout \begin_layout Plain Layout float2 tex : TEXCOORD, \end_layout \begin_layout Plain Layout out float2 out_tex : TEXCOORD \end_layout \begin_layout Plain Layout ) \end_layout \begin_layout Plain Layout { \end_layout \begin_layout Plain Layout out_pos = mul(modelViewProj, pos); \end_layout \begin_layout Plain Layout out_color = color; \end_layout \begin_layout Plain Layout out_tex = tex; \end_layout \begin_layout Plain Layout } \end_layout \end_inset \end_layout \begin_layout Standard This looks vaguely familiar to C, and it is. \begin_inset Index idx status open \begin_layout Plain Layout Cg \end_layout \end_inset Cg stands for \begin_inset Quotes eld \end_inset C for graphics \begin_inset Quotes erd \end_inset after all. We notice some things are happening, notable some new types. \end_layout \begin_layout Subsection Cg types \end_layout \begin_layout Subsubsection Float4 \end_layout \begin_layout Standard float4 is a vector type. It contains 4 elements. It could be colors, positions, whatever. It's used for vector processing which the GPUs are extremely efficient at. \end_layout \begin_layout Subsubsection Semantics \end_layout \begin_layout Standard We see various semantics. The POSITION semantic means that the variable is tied to vertex coordinates. We see that we have an input POSITION, and an output (out) POSITION. We thus transform the input to the output with a matrix multiply with the current model-view projection. Since this matrix is the same for every vertex, it is a uniform. Remember that the variable names DO matter. modelViewProj has to be called exactly that, as the emulator will pass the MVP to this uniform. It is in the specification. \end_layout \begin_layout Standard Since we have semantics for the POSITION, etc, we can call them whatever we want, as the Cg environment figures out what the variables mean. \end_layout \begin_layout Standard The transformation happens here: \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout out_pos = mul(modelViewProj, pos); \end_layout \end_inset \end_layout \begin_layout Standard The COLOR semantic isn't very interesting for us, but the example code in nVidias Cg documentation includes it, so we just follow along. \end_layout \begin_layout Standard TEXCOORD is the texture coordinate we get from the emulator, and generally we just pass it to the fragment shader directly. The coordinate will then be \begin_inset Quotes eld \end_inset linearly interpolated \begin_inset Quotes erd \end_inset across the fragments. More complex shaders can output (almost) as many variables they want, that will be linearily interpolated for free to the fragment shader. \end_layout \begin_layout Standard We also need a fragment shader to go along with the vertex shader, and here's a basic shader that only outputs the pixel as-is. This is pretty much the result you'd get if you didn't run any shader (fixed-fu nction) at all. \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout float4 main_fragment(uniform sampler2D s0 : TEXUNIT0, \end_layout \begin_layout Plain Layout float2 tex : TEXCOORD) : COLOR \end_layout \begin_layout Plain Layout { \end_layout \begin_layout Plain Layout return tex2D(s0, tex); \end_layout \begin_layout Plain Layout } \end_layout \end_inset \end_layout \begin_layout Standard This is arguably simpler than the vertex shader. Important to notice are: \end_layout \begin_layout Standard sampler2D is a handle to a texture in Cg. The semantic here is TEXUNIT0, which means that it refers to the texture in texture unit 0. This is also part of the specification. \end_layout \begin_layout Standard float2 tex : TEXCOORD is the interpolated coordinate we received from the vertex shader. \end_layout \begin_layout Standard tex2D(s0, tex); simply does texture lookup and returns a COLOR, which is emitted to the framebuffer. Simple enough. Practically every fragment does more than one texture lookup. For example, classic pixel shaders look at the neighbor pixels as well to determine the output. But where is the neighbor pixel? We'll revise the fragment shader and try to make a really blurry shader to demonstrate. We now need to pull up some uniforms. We need to know how to modify our tex coordinates so that it points to a neighbor pixel. \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout struct input \end_layout \begin_layout Plain Layout { \end_layout \begin_layout Plain Layout float2 video_size; \end_layout \begin_layout Plain Layout float2 texture_size; \end_layout \begin_layout Plain Layout float2 output_size; \end_layout \begin_layout Plain Layout float frame_count; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout float4 main_fragment(uniform sampler2D s0 : TEXUNIT0, \end_layout \begin_layout Plain Layout uniform input IN, float2 tex : TEXCOORD) : COLOR \end_layout \begin_layout Plain Layout { \end_layout \begin_layout Plain Layout float4 result = float4(0.0); \end_layout \begin_layout Plain Layout float dx = 1.0 / IN.texture_size.x; \end_layout \begin_layout Plain Layout float dy = 1.0 / IN.texture_size.y; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout // Grab some of the neighboring pixels and \end_layout \begin_layout Plain Layout // blend together for a very mushy blur. \end_layout \begin_layout Plain Layout result += tex2D(s0, tex + float2(-dx, -dy)); \end_layout \begin_layout Plain Layout result += tex2D(s0, tex + float2(dx, -dy)); \end_layout \begin_layout Plain Layout result += tex2D(s0, tex + float2(0.0, 0.0)); \end_layout \begin_layout Plain Layout result += tex2D(s0, tex + float2(-dx, 0.0)); \end_layout \begin_layout Plain Layout return result / 4.0; \end_layout \begin_layout Plain Layout } \end_layout \end_inset \end_layout \begin_layout Standard Here we use IN.texture_size to determine the the size of the texture. Since GL maps the whole texture to the interval [0.0, 1.0], 1.0 / IN.texture_size means we get the offset for a single pixel, simple enough. Almost every shader uses this. We can calculate these offsets in vertex shader to improve performance since the coordinates are linearily interpolated anyways, but that is for another time ... ;) \end_layout \begin_layout Subsection Putting it together \end_layout \begin_layout Standard The final runnable product is a single .cg file with the main_vertex and main_fragment functions added together. Not very complicated. For the icing on the cake, you should add a license header. \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout /* Stupid blur shader. \end_layout \begin_layout Plain Layout Author: Your friendly neighbor. \end_layout \begin_layout Plain Layout License: We don't have those things! \end_layout \begin_layout Plain Layout */ \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout struct input \end_layout \begin_layout Plain Layout { \end_layout \begin_layout Plain Layout float2 video_size; \end_layout \begin_layout Plain Layout float2 texture_size; \end_layout \begin_layout Plain Layout float2 output_size; \end_layout \begin_layout Plain Layout float frame_count; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout void main_vertex( \end_layout \begin_layout Plain Layout float4 pos : POSITION, \end_layout \begin_layout Plain Layout out float4 out_pos : POSITION, \end_layout \begin_layout Plain Layout uniform float4x4 modelViewProj, \end_layout \begin_layout Plain Layout float4 color : COLOR, \end_layout \begin_layout Plain Layout out float4 out_color : COLOR, \end_layout \begin_layout Plain Layout float2 tex : TEXCOORD, \end_layout \begin_layout Plain Layout out float2 out_tex : TEXCOORD \end_layout \begin_layout Plain Layout ) \end_layout \begin_layout Plain Layout { \end_layout \begin_layout Plain Layout out_pos = mul(modelViewProj, pos); \end_layout \begin_layout Plain Layout out_color = color; out_tex = tex; \end_layout \begin_layout Plain Layout } \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout float4 main_fragment(uniform sampler2D s0 : TEXUNIT0, \end_layout \begin_layout Plain Layout uniform input IN, float2 tex : TEXCOORD) : COLOR \end_layout \begin_layout Plain Layout { \end_layout \begin_layout Plain Layout float4 result = float4(0.0); \end_layout \begin_layout Plain Layout float dx = 1.0 / IN.texture_size.x; \end_layout \begin_layout Plain Layout float dy = 1.0 / IN.texture_size.y; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout // Grab some of the neighboring pixels and blend \end_layout \begin_layout Plain Layout // together for a very mushy blur. \end_layout \begin_layout Plain Layout result += tex2D(s0, tex + float2(-dx, -dy)); \end_layout \begin_layout Plain Layout result += tex2D(s0, tex + float2(dx, -dy)); \end_layout \begin_layout Plain Layout result += tex2D(s0, tex + float2(0.0, 0.0)); \end_layout \begin_layout Plain Layout result += tex2D(s0, tex + float2(-dx, 0.0)); \end_layout \begin_layout Plain Layout return result / 4.0; \end_layout \begin_layout Plain Layout } \end_layout \end_inset \end_layout \begin_layout Subsection Result \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename supermetroid.jpg lyxscale 50 scale 30 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash caption{The result of the shader code.} \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Standard As you can see, it's not a practical shader, but it shows the blurring effect to the extreme. \end_layout \begin_layout Section Expanding further \end_layout \begin_layout Subsection Lookup textures \end_layout \begin_layout Standard We'll first mention a very popular feature among RetroArch users the ability to access external textures. This means we have several samplers available for use. In the config file, we define the textures as so: \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout textures = "foo;bar" \end_layout \begin_layout Plain Layout foo = path_foo.png \end_layout \begin_layout Plain Layout bar = bar_foo.png \end_layout \begin_layout Plain Layout foo_linear = true # Linear filtering for foo. \end_layout \begin_layout Plain Layout bar_linear = true # Linear filtering for bar. \end_layout \end_inset \end_layout \begin_layout Standard RetroArch PS3 uses PNG as the main format, RetroArch can use whatever if Imlib2 support is compiled in. If not, it's restricted to lop-left ordered, non-RLE TGA. \end_layout \begin_layout Standard From here on, \begin_inset Quotes eld \end_inset foo \begin_inset Quotes erd \end_inset and \begin_inset Quotes eld \end_inset bar \begin_inset Quotes erd \end_inset can be found as uniforms in the shaders. The texture coordinates for the lookup texture will be found in TEXCOORD1. This can simply be passed along with TEXCOORD0 in the vertex shader as we did with TEXCOORD0. Here we make a fragment shader that blends in two background picture at a reduced opacity. Do NOT assign lookup textures to a certain TEXUNIT, Cg will assign a fitting texture unit to the sampler. \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout float4 main_fragment(uniform sampler2D s0 : TEXUNIT0, \end_layout \begin_layout Plain Layout uniform sampler2D foo, uniform sampler2D bar, \end_layout \begin_layout Plain Layout float2 tex : TEXCOORD0, float2 tex_lut : TEXCOORD1) : COLOR \end_layout \begin_layout Plain Layout { \end_layout \begin_layout Plain Layout float4 bg_sum = (tex2D(foo, tex_lut) + tex2D(bar, tex_lut)) * 0.15; \end_layout \begin_layout Plain Layout return lerp(tex2D(s0, tex), bg_sum, bg_sum.a); // Alpha blending. \end_layout \begin_layout Plain Layout } \end_layout \end_inset Here's an example of what can be achieved using borders (which are just a simple lookup texture): \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename shader-rarch-2.jpg lyxscale 50 scale 50 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash caption{A shader making use of a lookup texture for the purpose of drawing a background border.} \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Subsection Multipass \end_layout \begin_layout Standard It is sometimes feasible to process an effect in several steps. \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout shaders = 2 \end_layout \begin_layout Plain Layout shader0 = pass1.cg \end_layout \begin_layout Plain Layout shader1 = pass2.cg \end_layout \begin_layout Plain Layout scale_type0 = source \end_layout \begin_layout Plain Layout scale0 = 2.0 \end_layout \begin_layout Plain Layout filter_linear0 = true \end_layout \begin_layout Plain Layout filter_linear1 = false \end_layout \end_inset \end_layout \begin_layout Subsection Game-aware shaders \end_layout \begin_layout Standard This is a new and exciting feature. It allows shaders to grab data from the emulator state itself, such as RAM data. This is only implemented for SNES so far, but the idea is quite extendable and portable. \end_layout \begin_layout Standard The basic idea is that we capture RAM data in a certain way (semantic if you will) from the SNES, and pass it as a uniform to the shader. The shader can thus act on game state in interesting ways. \end_layout \begin_layout Standard As a tool to show this feature, we'll focus on replicating the simple tech demo shown on YouTube: \begin_inset CommandInset href LatexCommand href target "http://www.youtube.com/watch?v=4VzaE9q735k" \end_inset \end_layout \begin_layout Standard What happens is that when Mario jumps in the water, the screen gets a \begin_inset Quotes eld \end_inset watery \begin_inset Quotes erd \end_inset effect applied to it, with a rain lookup texture, and a wavy effect. When he jumps out of the water, the water effect slowly fades away. \end_layout \begin_layout Standard We thus need to know two things: \end_layout \begin_layout Itemize Is Mario currently in water or not? \end_layout \begin_layout Itemize If not, how long time was it since he jumped out? \end_layout \begin_layout Standard Since shaders do not have state associated with it, we have to let the environme nt provide the state we need in a certain way. We'll call this concept a semantic. \end_layout \begin_layout Standard To capture a RAM value directly, we can use the \begin_inset Quotes eld \end_inset capture \begin_inset Quotes erd \end_inset semantic. To record the time when the RAM value last changed, we can use the \begin_inset Quotes eld \end_inset transition \begin_inset Quotes erd \end_inset semantic. We obviously also need to know where in RAM we can find this information. Luckily, the guys over at SMW Central know the answer: \begin_inset CommandInset href LatexCommand href target "http://www.smwcentral.net/?p=map&type=ram" \end_inset \end_layout \begin_layout Standard We see: \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout $7E:0075, byte, Flag, Player is in water flag. #$00 = No; #$01 = Yes. \end_layout \end_inset Bank $7E and $7F are mapped to WRAM $0000-$FFFF and $10000-$1FFFF respectively. Thus, our WRAM address is $0075. \end_layout \begin_layout Standard In the config file, we can now set up the uniforms we'll want to be captured in the config file. \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout imports = "mario_water;mario_water_time" \end_layout \begin_layout Plain Layout mario_water_semantic = capture \end_layout \begin_layout Plain Layout # Capture the RAM value as-is. \end_layout \begin_layout Plain Layout mario_water_wram = 0075 \end_layout \begin_layout Plain Layout # This value is hex! \end_layout \begin_layout Plain Layout mario_water_time_semantic = transition \end_layout \begin_layout Plain Layout # Capture the frame count when this variable last changed. \end_layout \begin_layout Plain Layout # Use with IN.frame_count, to create a fade-out effect. \end_layout \begin_layout Plain Layout mario_water_time_wram = 0075 \end_layout \end_inset \end_layout \begin_layout Standard The amount of possible \begin_inset Quotes eld \end_inset semantics \begin_inset Quotes erd \end_inset are practically endless. It might be worthwhile to attempt some possibility to run custom code that keeps track of the shader uniforms in more sophisticated ways later on. Do note that there is also a %s_mask value which will let you bitmask the RAM value to check for bit-flags more easily. \end_layout \begin_layout Standard Now that we got that part down, let's work on the shader design. In the fragment shader we simply render both the full water effect, and the «normal» texture, and let a \begin_inset Quotes eld \end_inset blend \begin_inset Quotes erd \end_inset variable decide. We can say that 1.0 is full water effect, 0.0 is no effect. We can start working on our vertex shader. We will do something useful here for once. \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout struct input \end_layout \begin_layout Plain Layout { \end_layout \begin_layout Plain Layout float frame_count; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout void main_vertex( \end_layout \begin_layout Plain Layout float4 pos : POSITION, \end_layout \begin_layout Plain Layout out float4 out_pos : POSITION, \end_layout \begin_layout Plain Layout uniform float4x4 modelViewProj, \end_layout \begin_layout Plain Layout float4 color : COLOR, \end_layout \begin_layout Plain Layout out float4 out_color : COLOR, \end_layout \begin_layout Plain Layout float2 tex : TEXCOORD0, \end_layout \begin_layout Plain Layout out float2 out_tex : TEXCOORD0, \end_layout \begin_layout Plain Layout float2 tex1 : TEXCOORD1, \end_layout \begin_layout Plain Layout out float2 out_tex1 : TEXCOORD1, \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout // Even if the data should have been int, \end_layout \begin_layout Plain Layout // Cg doesn't seem to \end_layout \begin_layout Plain Layout uniform float mario_water, \end_layout \begin_layout Plain Layout // support integer uniforms \end_layout \begin_layout Plain Layout uniform float mario_water_time, \end_layout \begin_layout Plain Layout uniform input IN, \end_layout \begin_layout Plain Layout // Blend factor is passed to fragment shader. \end_layout \begin_layout Plain Layout // We'll output the same value in every vertex, \end_layout \begin_layout Plain Layout // so every fragment will get the same value \end_layout \begin_layout Plain Layout // for blend_factor since there is nothing to interpolate. \end_layout \begin_layout Plain Layout out float blend_factor ) \end_layout \begin_layout Plain Layout { \end_layout \begin_layout Plain Layout out_pos = mul(modelViewProj, pos); \end_layout \begin_layout Plain Layout out_color = color; \end_layout \begin_layout Plain Layout out_tex = tex; \end_layout \begin_layout Plain Layout out_tex1 = tex1; \end_layout \begin_layout Plain Layout float transition_time = 0.5 * \end_layout \begin_layout Plain Layout (IN.frame_count – mario_water_time) / 60.0; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout // If Mario is in the water ($0075 != 0), \end_layout \begin_layout Plain Layout // it's always 1 ... \end_layout \begin_layout Plain Layout if (mario_water > 0.0) \end_layout \begin_layout Plain Layout blend_factor = 1.0; \end_layout \begin_layout Plain Layout // Fade out from 1.0 towards 0.0 as \end_layout \begin_layout Plain Layout // transition_time grows larger. \end_layout \begin_layout Plain Layout else \end_layout \begin_layout Plain Layout blend_factor = exp(-transition_time); \end_layout \begin_layout Plain Layout } \end_layout \end_inset \end_layout \begin_layout Standard All fine and dandy so far, now we just need to use this blend_factor in our fragment shader somehow ... Let's move on to the fragment shader where we blend. \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout float apply_wave(float2 pos, float2 src, float cnt) \end_layout \begin_layout Plain Layout { \end_layout \begin_layout Plain Layout float2 diff = pos - src; \end_layout \begin_layout Plain Layout float dist = 300.0 * sqrt(dot(diff, diff)); \end_layout \begin_layout Plain Layout dist -= 0.15 * cnt; \end_layout \begin_layout Plain Layout return sin(dist); \end_layout \begin_layout Plain Layout } \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout // Fancy shizz to create a wave. \end_layout \begin_layout Plain Layout float4 water_texture(float4 output, float2 scale, float cnt) \end_layout \begin_layout Plain Layout { \end_layout \begin_layout Plain Layout float res = apply_wave(scale, src0, cnt); \end_layout \begin_layout Plain Layout res += apply_wave(scale, src1, cnt); \end_layout \begin_layout Plain Layout res += apply_wave(scale, src2, cnt); \end_layout \begin_layout Plain Layout res += apply_wave(scale, src3, cnt); \end_layout \begin_layout Plain Layout res += apply_wave(scale, src4, cnt); \end_layout \begin_layout Plain Layout res += apply_wave(scale, src5, cnt); \end_layout \begin_layout Plain Layout res += apply_wave(scale, src6, cnt); \end_layout \begin_layout Plain Layout return output * (0.95 + 0.012 * res); \end_layout \begin_layout Plain Layout } \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout float4 main_fragment \end_layout \begin_layout Plain Layout ( \end_layout \begin_layout Plain Layout uniform input IN, \end_layout \begin_layout Plain Layout float2 tex : TEXCOORD0, uniform sampler2D s0 : TEXUNIT0, \end_layout \begin_layout Plain Layout uniform sampler2D rain, float2 tex1 : TEXCOORD1, \end_layout \begin_layout Plain Layout in float blend_factor // Passed from vertex \end_layout \begin_layout Plain Layout ) : COLOR \end_layout \begin_layout Plain Layout { \end_layout \begin_layout Plain Layout float4 water_tex = water_texture(tex2D(s0, tex), tex1, IN.frame_count); \end_layout \begin_layout Plain Layout float4 normal_tex = tex2D(s0, tex); \end_layout \begin_layout Plain Layout float4 rain_tex = tex2D(rain, tex1); \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout // First, blend normal and water texture together, \end_layout \begin_layout Plain Layout // then add the rain texture with alpha blending on top \end_layout \begin_layout Plain Layout return lerp(lerp(normal_tex, water_tex, blend_factor), \end_layout \begin_layout Plain Layout rain_tex, rain_tex.a * blend_factor * 0.5); \end_layout \begin_layout Plain Layout } \end_layout \end_inset \end_layout \begin_layout Subsubsection RetroArch config file \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout shaders = 1 \end_layout \begin_layout Plain Layout shader0 = mario.cg \end_layout \begin_layout Plain Layout filter_linear0 = true \end_layout \begin_layout Plain Layout imports = "mario_water;mario_water_time" \end_layout \begin_layout Plain Layout mario_water_semantic = capture \end_layout \begin_layout Plain Layout mario_water_time_semantic = transition \end_layout \begin_layout Plain Layout mario_water_wram = 0075 \end_layout \begin_layout Plain Layout mario_water_time_wram = 0075 \end_layout \begin_layout Plain Layout textures = rain \end_layout \begin_layout Plain Layout rain = rain.tga \end_layout \begin_layout Plain Layout rain_linear = true \end_layout \end_inset \end_layout \begin_layout Subsubsection How to test when developing for RetroArch? \end_layout \begin_layout Standard To develop these kinds of shaders, I'd recommend using \begin_inset Index idx status open \begin_layout Plain Layout RetroArch \end_layout \end_inset RetroArch w/ \begin_inset Index idx status open \begin_layout Plain Layout Cg \end_layout \end_inset Cg support, and a debugging tool for your emulator of choice to peek at RAM values (build it for \begin_inset Index idx status open \begin_layout Plain Layout bSNES \end_layout \end_inset bSNES yourself with options=debugger). \end_layout \begin_layout Standard After written, the shader should translate nicely over to RetroArch with some slight changes to the config. \end_layout \begin_layout Subsubsection Results \end_layout \begin_layout Standard Here are some screenshots of the mario effect (in Super Mario World SNES) we developed. Obviously this is a very simple example showing what can be done. It's not confined to overlays. The imagination is the limit here. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename mario-water1.jpg lyxscale 50 scale 50 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash caption{Super Mario World prior to Mario jumping in water.} \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename mario-water2.jpg lyxscale 50 scale 50 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash caption{Super Mario World with a game aware shader applying a LUT texture as soon as Mario jumps into the water.} \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Standard \begin_inset CommandInset index_print LatexCommand printindex type "idx" \end_inset \end_layout \end_body \end_document ================================================ FILE: archive/libretro.lyx ================================================ #LyX 2.0 created this file. For more info see http://www.lyx.org/ \lyxformat 413 \begin_document \begin_header \textclass article \use_default_options true \maintain_unincluded_children false \language english \language_package default \inputencoding auto \fontencoding global \font_roman default \font_sans default \font_typewriter default \font_default_family default \use_non_tex_fonts false \font_sc false \font_osf false \font_sf_scale 100 \font_tt_scale 100 \graphics default \default_output_format default \output_sync 0 \bibtex_command default \index_command default \paperfontsize default \spacing single \use_hyperref true \pdf_title "Libretro - Implementing the core" \pdf_author "Hans-Kristian Arntzen, Daniel De Matteis" \pdf_bookmarks true \pdf_bookmarksnumbered false \pdf_bookmarksopen false \pdf_bookmarksopenlevel 1 \pdf_breaklinks false \pdf_pdfborder true \pdf_colorlinks true \pdf_backref false \pdf_pdfusetitle true \papersize default \use_geometry false \use_amsmath 1 \use_esint 1 \use_mhchem 1 \use_mathdots 1 \cite_engine basic \use_bibtopic true \use_indices false \paperorientation portrait \suppress_date false \use_refstyle 1 \index Index \shortcut idx \color #008000 \end_index \secnumdepth 3 \tocdepth 3 \paragraph_separation indent \paragraph_indentation default \quotes_language english \papercolumns 1 \papersides 1 \paperpagestyle default \tracking_changes false \output_changes false \html_math_output 0 \html_css_as_file 0 \html_be_strict false \end_header \begin_body \begin_layout Title Libretro - Implementing the core \end_layout \begin_layout Author Hans-Kristian Arntzen, Daniel De Matteis \end_layout \begin_layout Standard \begin_inset CommandInset toc LatexCommand tableofcontents \end_inset \end_layout \begin_layout Abstract This document explains how to successfully implement a library based on the \begin_inset Index idx status open \begin_layout Plain Layout libretro \end_layout \end_inset libretro API. Several reasons for why more emulators and game engines should run in \begin_inset Index idx status open \begin_layout Plain Layout libretro \end_layout \end_inset libretro are outlined. \end_layout \begin_layout Section Background \end_layout \begin_layout Standard \begin_inset Index idx status open \begin_layout Plain Layout RetroArch \end_layout \end_inset RetroArch is a project that aims to be a center for “retro” gaming experiences. For your quick fix of 2D gaming goodness, \begin_inset Index idx status open \begin_layout Plain Layout RetroArch \end_layout \end_inset RetroArch aims to provide a simple, featureful uniform interface for many different gaming systems. \end_layout \begin_layout Standard \begin_inset Index idx status open \begin_layout Plain Layout libretro \end_layout \end_inset Libretro is an API that abstracts the inner functionality of a gaming system. \begin_inset Index idx status open \begin_layout Plain Layout RetroArch \end_layout \end_inset RetroArch can load a library that implements this API, give it a ROM, and play. A key design is that libretro implementations are loaded as libraries. This ensures great modularity, and flexibility for a developer of a core. \end_layout \begin_layout Standard Due to its simple and open API, other frontends can just as easily utilize libretro implementations. \end_layout \begin_layout Standard While “retro” would often imply an emulator of a classic system, \begin_inset Index idx status open \begin_layout Plain Layout libretro \end_layout \end_inset libretro can also abstract a game engine. Classics such as \begin_inset Index idx status open \begin_layout Plain Layout Cave Story \end_layout \end_inset Cave Story (NXEngine) and \begin_inset Index idx status open \begin_layout Plain Layout Doom \end_layout \end_inset DOOM (PrBoom) have already been ported over. \end_layout \begin_layout Section Portability \end_layout \begin_layout Standard Most emulator authors write both the backend and frontend to their project. The question of portability inevitably rises when the frontend is developed. Should one target a single platform with high level of integration or take a multi-platform approach with libraries like \begin_inset Index idx status open \begin_layout Plain Layout Qt \end_layout \end_inset Qt? Backends for essentials like video, audio and input take a lot of time and effort to get right, especially on multiple platforms. \end_layout \begin_layout Standard By implementing for \begin_inset Index idx status open \begin_layout Plain Layout libretro \end_layout \end_inset libretro, one can target standard C/C++ (or any language that can export a C API), and achieve instant portability across tons of platforms. \end_layout \begin_layout Standard In 2012, we would argue that portability has never been more relevant. There are three major operating systems on the desktop, two major smart phone platforms, and three gaming consoles. If your system is implemented with software rendering, your implementation can run on all systems supported by the frontend, without writing any platform specific code. In the case of \begin_inset Index idx status open \begin_layout Plain Layout RetroArch \end_layout \end_inset RetroArch these are currently: \end_layout \begin_layout Itemize Windows \end_layout \begin_layout Itemize Linux \end_layout \begin_layout Itemize OSX \end_layout \begin_layout Itemize GameCube \end_layout \begin_layout Itemize PlayStation 3 \end_layout \begin_layout Itemize XBox 1 \end_layout \begin_layout Itemize XBox 360 \end_layout \begin_layout Itemize Wii \end_layout \begin_layout Itemize Android \end_layout \begin_layout Section Features \end_layout \begin_layout Standard \begin_inset Index idx status open \begin_layout Plain Layout RetroArch \end_layout \end_inset RetroArch has been in development for about two years. During this time, some features have shown to be quinessential to retro gaming systems. Implementing the \begin_inset Index idx status open \begin_layout Plain Layout libretro \end_layout \end_inset libretro API correctly, these features can be utilized without any additional work. \end_layout \begin_layout Subsection Frame-by-frame rewind \end_layout \begin_layout Standard A libretro implementation that implements serialization and unserialization of internal state is able to transparently support rewind mechanics. While many emulators support coarse grained rewind, \begin_inset Index idx status open \begin_layout Plain Layout RetroArch \end_layout \end_inset RetroArch supports rewind at the frame level, i.e., frames can be rewound one frame at a time, similar to the indie-title \begin_inset Index idx status open \begin_layout Plain Layout Braid \end_layout \end_inset Braid. \end_layout \begin_layout Subsection \begin_inset Index idx status open \begin_layout Plain Layout FFmpeg \end_layout \end_inset FFmpeg lossless recording \end_layout \begin_layout Standard \begin_inset Index idx status open \begin_layout Plain Layout RetroArch \end_layout \end_inset RetroArch can utilize the \begin_inset Index idx status open \begin_layout Plain Layout libavcodec \end_layout \end_inset libavcodec library to encode video and audio output from a libretro implementati on. The data is encoded losslessly, with \begin_inset Index idx status open \begin_layout Plain Layout FLAC \end_layout \end_inset FLAC as audio codec, and cutting-edge \begin_inset Index idx status open \begin_layout Plain Layout H.264 \end_layout \end_inset H.264/RGB (libx264) encoding, with a fallback to FFV1 for older playback systems that don't support the modern \begin_inset Index idx status open \begin_layout Plain Layout H.264 \end_layout \end_inset H.264/RGB variant. The recorder is multithreaded, and easily performs real-time. \end_layout \begin_layout Subsection Advanced GPU shader support \end_layout \begin_layout Standard Classic 2D games have the advantage that their video output is very flexible, that is, it can be post- processed easily. Before the advent of programmable GPUs, video filters had to be performed on the main CPU, which cut directly into performance, and severely limited the types of filters possible to acheive in real-time. RetroArch aims to move this processing to the GPU by using shaders. A vast amount of shader effects are written already, and the shader format used is documented and implemented independently by other frontends as well. \end_layout \begin_layout Standard \begin_inset Index idx status open \begin_layout Plain Layout RetroArch \end_layout \end_inset RetroArch's shader support is more advanced than most emulators. It supports an arbitrary amount of shader passes, look-up textures (borders), scriptable shaders that can react dynamically to input or game content. \end_layout \begin_layout Standard \begin_inset Index idx status open \begin_layout Plain Layout RetroArch \end_layout \end_inset RetroArch still supports use of traditional CPU filters, however, it should be considered a fallback if GPU support is broken. \end_layout \begin_layout Subsection Peer-to-peer netplay \end_layout \begin_layout Standard \begin_inset Index idx status open \begin_layout Plain Layout RetroArch \end_layout \end_inset RetroArch supports two-player action over the network. It employs a rollback technique that aims to hide latency as much as possible, similar to the method employed by \begin_inset Index idx status open \begin_layout Plain Layout GGPO \end_layout \end_inset GGPO. \end_layout \begin_layout Standard In addition to head-to-head multiplayer, a spectator mode is implemented. This mode allows a host to live stream playback to several watchers in real-time. The bandwidth required for this mode is near- zero as only raw input data is transferred over the network. \end_layout \begin_layout Subsection Audio DSP plugins \end_layout \begin_layout Standard \begin_inset Index idx status open \begin_layout Plain Layout RetroArch \end_layout \end_inset RetroArch supports plugins that allows post-processing of audio data, similar to post-processing of video data. It supports use of on-the-fly configurable plugins with aid of a GUI. \end_layout \begin_layout Section Implementing the API \end_layout \begin_layout Standard The \begin_inset Index idx status open \begin_layout Plain Layout libretro \end_layout \end_inset libretro API consists of several functions outlined in libretro.h, found in the \begin_inset Index idx status open \begin_layout Plain Layout RetroArch \end_layout \end_inset RetroArch source package. A libretro implementation should be compiled into a dynamically loadable executable (.dll/.so/.dylib) or a static library (.a/.lib) that exports all the functions outlined in libretro.h. These will be called by the frontend. Implementations are designed to be single-instance, so global state is allowed. Should the frontend call these functions in wrong order, undefined behavior occurs. \end_layout \begin_layout Standard The API header is compatible with \begin_inset Index idx status open \begin_layout Plain Layout C99 \end_layout \end_inset C99 and \begin_inset Index idx status open \begin_layout Plain Layout C++ \end_layout \end_inset C++. From \begin_inset Index idx status open \begin_layout Plain Layout C99 \end_layout \end_inset C99, the bool type and are used. \end_layout \begin_layout Standard The program flow of a frontend using the \begin_inset Index idx status open \begin_layout Plain Layout libretro \end_layout \end_inset libretro API can be expressed as follows: \end_layout \begin_layout Subsection Startup \end_layout \begin_layout Subsubsection retro_api_version() \end_layout \begin_layout Standard This function should return RETRO_API_VERSION, defined in libretro.h. It is used by the frontend to determine if ABI/API are mismatched. The version will be bumped should there be any non- compatible changes to the API. Changes to retro_* structures, as well as changes in publically visible functions and/or their arguments will warrant a bump in API version. \end_layout \begin_layout Subsubsection retro_init() \end_layout \begin_layout Standard This function is called once, and gives the implementation a chance to initializ e data structures. This is sometimes implemented as a no-op. \end_layout \begin_layout Subsubsection retro_set_*() \end_layout \begin_layout Standard \begin_inset Index idx status open \begin_layout Plain Layout libretro \end_layout \end_inset Libretro is callback based. The frontend will set all callbacks at this stage, and the implementation must store these function pointers somewhere. The frontend can, at a later stage, call these. \end_layout \begin_layout Subsubsection Environment callback \end_layout \begin_layout Standard While \begin_inset Index idx status open \begin_layout Plain Layout libretro \end_layout \end_inset libretro has callbacks for video, audio and input, there's a callback type dubbed the environment callback. This callback (retro_environment_t) is a generic way for the \begin_inset Index idx status open \begin_layout Plain Layout libretro \end_layout \end_inset libretro implementation to access features of the API that are considered too obscure to deserve its own symbols. It can be extended without breaking \begin_inset Index idx status open \begin_layout Plain Layout ABI \end_layout \end_inset ABI. The callback has a return type of bool which tells if the frontend recognized the request given to it. \end_layout \begin_layout Standard Most implementations of \begin_inset Index idx status open \begin_layout Plain Layout libretro \end_layout \end_inset libretro will not use this callback at all. \end_layout \begin_layout Subsubsection retro_set_controller_port_device() \end_layout \begin_layout Standard By default, joypads will be assumed to be inserted into the implementation. If the engine is sensitive to which type of input device is plugged in, the frontend may call this function to set the device to be used for a certain player. The implementation should try to auto-detect this if possible. \end_layout \begin_layout Subsubsection retro_get_system_info() \end_layout \begin_layout Standard The frontend will typically request statically known information about the core such as the name of the implementation, version number, etc. The information returned should be stored statically. If dynamic allocation must take place, the implementation must make sure to free this storage in retro_deinit() later. \end_layout \begin_layout Subsubsection retro_load_game() \end_layout \begin_layout Standard This function will load a ROM that the implementation will use to play the game. If the implementation is an emulator, this would be a game ROM image, if it is a game engine, this could be packaged upassets for the game, etc. The function takes a structure that points to the path where the ROM was loaded from, as well as a memory chunk of the already loaded file. \end_layout \begin_layout Standard There are two modes of loading files with libretro. If the game engine requires to know the path of where the ROM image was loaded from, the need_fullpath field in retro_system_info must be set to true. If the path is required, the frontend will not load the file into the data/size fields, and it is up to the implementation to load the file from disk. The path might be both relative and absolute, and the implementation must check for both cases. \end_layout \begin_layout Standard This is useful if the ROM image is too large to load into memory at once. It is also useful if the assests consist of many smaller files, where it is necessary to know the path of a master file to infer the paths of the others. If need_fullpath is set to false, the frontend will load the ROM image into memory beforehand. In this mode, the path field is not guaranteed to be non-NULL. It should point to a valid path if the file was indeed, loaded from disk, however, it is possible that the file was loaded from stdin, or similar, which has no well-defined path. \end_layout \begin_layout Standard It is recommended that need_fullpath is set to false if possible, as it allows more features, such as soft- patching to work correctly. \end_layout \begin_layout Standard retro_load_game_special() is a special case of retro_load_game(). It is designed to allow the loading of several ROMs together. This is needed for certain odd cases like Super Nintendo with e.g. Super GameBoy, Sufami Turbo, etc that consist of a "BIOS" + Game(s). The function takes the type of game as an argument, and if a new game type is to be added, it needs to be reserved in the libretro.h header. Almost any libretro implementations should simply implement this as return false;. If a game consist of many smaller files it is encouraged to load a single zipped file, or something similar. \end_layout \begin_layout Standard Each ROM image can take an optional meta-argument, a string that gives extra metadeta to the implementation. The metadata is implementation specific, and can be ignored completely in almost any implementation. \end_layout \begin_layout Subsubsection retro_get_system_av_info() \end_layout \begin_layout Standard This function lets the frontend know essential audio/video properties of the game. As this information can depend on the game being loaded, this info will only be queried after a valid ROM image has been loaded. It is important to accuractely report FPS and audio sampling rates, as \begin_inset Index idx status open \begin_layout Plain Layout FFmpeg \end_layout \end_inset FFmpeg recording relies on exact information to be able to run in sync for several hours. \end_layout \begin_layout Subsection Running \end_layout \begin_layout Subsubsection retro_run() \end_layout \begin_layout Standard After a game has been loaded successfully, retro_run() will be called repeatedly as long as the user desires. When called, the implementation will perform its inner functionality for one video frame. During this time, the implementation is free to call callbacks for video frames, audio samples, as well as polling input, and querying current input state. The requirements for the callbacks are that video callback is called exactly once, i.e. it does not have to come last. Also, input polling must be called at least once. \end_layout \begin_layout Subsubsection Video/Audio synchronization considerations \end_layout \begin_layout Standard Libretro is based on fixed rates. Video FPS and audio sampling rates are always assumed to be constant. Frontends will have control of the speed of playing, typically using VSync to obtain correctspeed. The frontend is free to "fast-forward", i.e. play as fast as possible without waiting, or slow- motion. For this reason, the engine should not rely on system timers to perform arbitrary synchronization. This is common and often needed in 3D games to account for varying frame rates while still maintaining a playable game. However, libretro targets classic systems where one can assume that 100 % real-time performance will always be met, thus avoiding the need for careful timing code. \end_layout \begin_layout Standard By default, the libretro implementation should replace any arbitrary sleep()/tim e() patterns with simply calling video/audio callbacks. The frontend will make sure to apply the proper synchronization. \end_layout \begin_layout Standard This is mostly a problem with game ports, such as PrBoom. For the libretro port of PrBoom, which heavily relied on timers and sleeping patterns, sleeping was replaced with simply running for one frame, and calling the video callback. After that, enough audio was rendered to correspond to one frames worth of time, 1 / fps seconds. All sleeping and timing patterns could be removed, and synchronization was correct. \end_layout \begin_layout Subsubsection Audio callback considerations \end_layout \begin_layout Standard The \begin_inset Index idx status open \begin_layout Plain Layout libretro \end_layout \end_inset libretro API has two different audio callbacks. Only one of these should be used; the implementation must choose which callback is best suited. \end_layout \begin_layout Standard The first audio callback is per-sample, and has the type void (*)(int16_t, int16_t). This should be used if the implementation outputs audio on a per-sample basis. The frontend will make sure to partition the audio data into suitable chunks to avoid incurring too much syscall overhead. \end_layout \begin_layout Standard If audio is output in a "batch" fashion, i.e. 1 / fps seconds worth of audio data at a time, the batch approach should be considered. Rather than looping over all samples and calling per-sample callback every time, the batch callback should be used instead, size_t (*)(const int16_t *, size_t). \end_layout \begin_layout Standard Using the batch callback, audio will not be copied in a temporary buffer, which can buy a slight performance gain. Also, all data will be pushed to audio driver in one go, saving some slight overhead. It is not recommended to use the batch callback for very small (< 32 frames) amounts of data. \end_layout \begin_layout Standard The data passed to the batch callback should, if possible, be aligned to 16 bytes (depends on platform), to allow accelerated \begin_inset Index idx status open \begin_layout Plain Layout SIMD \end_layout \end_inset SIMD operations on audio. \begin_inset Index idx status open \begin_layout Plain Layout RetroArch \end_layout \end_inset RetroArch implements \begin_inset Index idx status open \begin_layout Plain Layout SSE \end_layout \end_inset SSE/ \begin_inset Index idx status open \begin_layout Plain Layout AltiVec \end_layout \end_inset AltiVec optimized audio processing for conversions and resampling. \end_layout \begin_layout Subsubsection Input device abstraction \end_layout \begin_layout Standard Abstracting input devices is the hardest part of defining a multi-system API as it differs across every system. The common input devices are: \end_layout \begin_layout Itemize Joypad (with or without analogs) \end_layout \begin_layout Itemize Mouse (e.g. SNES mouse) \end_layout \begin_layout Itemize Keyboard (e.g. Commodore, Amiga) \end_layout \begin_layout Itemize Lightguns (e.g. SNES SuperScope) \end_layout \begin_layout Standard The joypad abstraction is the most interesting. Rather than complicating things by mapping input arbitrarily in terms of the implementation, which would make input configuration very complex with careful configuration on a per-implementation basis, an abstract joypad device, the \begin_inset Index idx status open \begin_layout Plain Layout Input device abstractions!RetroPad \end_layout \end_inset RetroPad, was devised. \end_layout \begin_layout Standard This joypad is essentially the Super Nintendo controller, widely considered the pinnacle of retro game controllers. To account for more modern systems with additional buttons, additions from the PlayStation DualShock are incorporated, with extra shoulder buttons (L2/R2), as well as depressable analogs (L3/R3). In addition, the RETRO_DEVICE_ANALOG is used for analog stick data. An implementation should map its idea of a joypad in terms of the \begin_inset Index idx status open \begin_layout Plain Layout Input device abstractions!RetroPad \end_layout \end_inset RetroPad, which is what most users will have to use with their frontend. \end_layout \begin_layout Subsubsection retro_serialize_size() \end_layout \begin_layout Subsubsection retro_serialize() \end_layout \begin_layout Subsubsection retro_unserialize() \end_layout \begin_layout Standard Serialization is optional to implement. Serialization is better known as "save states" in emulators, and these functions are certainly more useful in emulators which have a fixed amount of state. It allows the frontend to take a snapshot of all internal state, and later restore it. This functionality is used to implement e.g. rewind and netplay. Some important considerations must be taken to implement these functions well. \end_layout \begin_layout Standard If serialization is not supported, retro_serialize_size() should return 0. If retro_serialize_size() returns non-zero, it is assumed that serialization is properly implemented. \end_layout \begin_layout Standard The frontend should call retro_serialize_size() before calling retro_serialize() to determine the amount of memory needed to correctly serialize. The size eventually passed to retro_serialize() must be at least the size of the value returned in retro_serialize_size(). If too large a buffer is passed to retro_serialize(), the extra data should be ignored (or memset to 0). \end_layout \begin_layout Standard It is valid for the value returned by retro_serialize_size() to vary over time, however, it cannot ever increase over time. If it should ever change, it must decrease. This is rationaled by the ability to pre- determined a fixed save state size right after retro_load_game() that will always be large enough to hold any following serialization. This certainty is fundamental to the rewind implementation. This requirement only holds between calls to retro_load_game() and retro_unload _game(). \end_layout \begin_layout Standard If possible, the implementation should attempt to serialize data at consistent offsets in the memory buffer. This will greatly help the rewind implementation in \begin_inset Index idx status open \begin_layout Plain Layout RetroArch \end_layout \end_inset RetroArch to use less memory. \end_layout \begin_layout Standard Both retro_serialize() and retro_unserialize() return a boolean value to let the frontend know if the implementation succeeded in serializing or unserializing. \end_layout \begin_layout Subsection Tear-down \end_layout \begin_layout Subsubsection retro_unload_game() \end_layout \begin_layout Standard After the user desired to stop playing, retro_unload_game() will be called. This should free any internal data related to the game, and allow retro_load_ga me() to be called again. \end_layout \begin_layout Subsubsection retro_deinit() \end_layout \begin_layout Standard This function should free all state that was initialized during retro_init(). After calling this function, the frontend can again call retro_init(). \end_layout \begin_layout Standard \begin_inset CommandInset index_print LatexCommand printindex type "idx" \end_inset \end_layout \end_body \end_document ================================================ FILE: archive/overlay.tex ================================================ \documentclass[a4paper, 11pt]{article} \title{RetroArch - Overlay image configuration} \author{ Hans-Kristian Arntzen \and Daniel De Matteis} \begin{document} \maketitle \section*{Purpose} RetroArch supports overlay images for use with hardware accelerated drivers. The purpose of this is to allow some kind of input interface that is mouse/touch oriented. The overlay image is displayed with transparency over the regular game image, and the user is able to trigger input by pressing on certain parts of the overlay. Since the overlay is an image, the user should be able to fully configure the look and functionality of this overlay. This allows skinners and themers to go wild. \section*{Configuration} The overlay is described in a config file (*.cfg). The config file uses the same config file syntax as RetroArch itself. The overlay system supports use of multiple overlays that can be switched out on the fly. Input is not only restricted to gamepad input, but can also work with any input that is bindable in RetroArch, e.g. save states, rewind, load state, etc. The config file describes: \begin{itemize} \item Which overlay images to use (.png, .tga, etc). \item Which coordinates on each overlay correspond to which input event. \item The hitbox for each input event, i.e. "size" of the button. \item Where on the screen the overlay should be displayed. \end{itemize} \subsection*{Overlay images} First we configure how many overlays we use, and where they can be found. \begin{verbatim} overlays = 2 overlay0_overlay = overlay_img0.png overlay1_overlay = overlay_img1.png \end{verbatim} The paths are relative to where the overlay config is loaded from. If the path is absolute, absolute paths will be used. On Unix-like systems '~/' is recognized as '\$HOME'. \subsection*{Screen placement} By default, the overlay image will be stretched out to fill the whole game image. However, for some overlays, this is not practical. It is possible to set the placement using for example: \begin{verbatim} overlay0_rect = "0.2,0.3,0.5,0.4" \end{verbatim} We assume that the game screen has normalized coordinates in X and Y that span from `[0, 0]` in the top-left corner to $[1, 1]$ in the lower-right corner. This will render the overlay to $x = 0.2, y = 0.3$ with size $width = 0.5, height = 0.4$. The default (stretch to full screen) could be described as such: \begin{verbatim} overlay0_rect = "0.0,0.0,1.0,1.0" \end{verbatim} \subsection*{Full-screen overlays} By default, overlays will be stretched out to fill game viewport. However, in some cases the aspect ratio of the game causes there to remain large black borders around the game image. It is possible to stretch the overlay to full screen (instead of viewport) by specifying this option: \begin{verbatim} overlay0_full_screen = true \end{verbatim} \subsection*{Coordinate descriptors} We must also describe where on the overlay image buttons can be found for each overlay. E.g.: \begin{verbatim} overlay0_descs = 3 # Three buttons for this overlay in total overlay0_desc0 = "a,32,64,radial,10,20" overlay0_desc1 = "start,100,50,rect,80,10" overlay0_desc2 = "overlay_next,200,180,radial,40,40" \end{verbatim} The format is: \begin{verbatim} "button,position_x,position_y,hitbox_type,range_x,range_y" \end{verbatim} 'button' corresponds to the input event being generated. The names are the same as in the general input config, e.g. input\_player1\_start would translate to start here. overlay\_next is a special bind designed to swap to the next overlay, or wrap around to the first one. 'position\_x' and 'position\_y' are the x and y coordinates in pixels of the source image for the center of the button. 'hitbox\_type' describes which type of shape the button has. 'radial' (circle, ellipsis) and 'rect' (rectangular) shapes are supported. 'range\_x' and 'range\_y' describe the size of the button. The semantics differ slightly for radial and rect hitbox types. For 'radial' shape, 'range\_x' and 'range\_y' describe the radius in x and y directions in pixels of the source image. For 'rect' shape, the 'range\_x' and 'range\_y' values represent the distance from center to the edge of the rect in terms of pixels of the source image. E.g. a 'range\_x' of 20 would mean the width of the rectangular is 40 pixels in total. \subsection*{Triggering multiple buttons with one desc} It's possible to trigger multiple buttons (e.g. diagonals) with one overlay desc. \begin{verbatim} overlay0_desc0 = "left|up,32,64,radial,10,20" \end{verbatim} will trigger both left and up at same time. \end{document} ================================================ FILE: archive/ratecontrol.tex ================================================ \documentclass[11pt, a4paper]{article} \title{Dynamic Rate Control for Retro Game Emulators} \author{Hans-Kristian Arntzen} \usepackage{amsmath} \usepackage{float} \usepackage{graphicx} \begin{document} \maketitle \begin{abstract} This article describes a method for game emulator frontends to synchronize both audio and video output at the same time, even when the emulating system has a different refresh rate and audio sampling rate than the gaming system that is being emulated. The method works by dynamically adjusting audio resampling ratios in such ways that ideally, the audio buffer is never underrun nor overrun, thus avoiding blocking on audio. This in turn allows vertical synchronization for video. The audio pitch is adjusted when adjusting audio resampling ratios, but in practice so little, that it is inaudible to the human ear. \end{abstract} \section{Background} Retro game consoles are highly synchronous. Their audio output rates are linked directly to video refresh rates. Every video frame, the audio chip generates on average a fixed amount of audio samples. Before continuing to emulate the next frame, the generated audio samples must be pushed to an audio buffer of fixed size. If there is not enough space in the audio buffer, the emulator must wait (block) for the buffer to become ready for writing. This is a non-ideal situation as while the emulator is blocking on audio, a vertical refresh might be missed entirely, thus creating stuttering video. \subsection{The ideal synchronization} For an emulator of a retro game system, a key factor in smooth video is vertical refresh synchronization (VSync), where each frame of the game maps to a single frame on the monitor. Audio must also be pushed to the speakers without any audio dropouts. This double synchronization requirement poses a problem as any form of synchronization to one modality will negatively affect the other. This is a real problem as an emulator has no way of guaranteeing perfectly equal video refresh rates and audio sampling rates as the original system. On conventional computer hardware, there is no perfect way of knowing the real monitor refresh rates and audio sampling rates either due to tolerances on oscillators. \subsection{Scope of method} As this method aims to implement a method for synchronization when VSync is used, this method is only useful when game frame rate is close to monitor frame rate. If this is not the case, other methods should be employed. \section{Method} This method assumes that audio from the emulator is output at regular intervals, e.g. every video frame. The method also assumes that audio is resampled from the game system sampling rate to the sound cards sampling rate. The resampling ratio will be dynamically adjusted every time audio is resampled and subsequently pushed to the audio buffer. \subsection{Definitions} \begin{itemize} \item[$f_v$] Emulated game system frame rate (FPS) \item[$f_a$] Emulated game system sampling rate (Hz) \item[$r$] Emulated game system samples per frame $f_a / f_v$ \item[$m_a$] Emulator system sampling rate \item[$m_v$] Emulator system monitor refresh rate \item[$m_a^{'}$] Estimated emulator system sampling rate \item[$m_v^{'}$] Estimated emulator system monitor refresh rate \item[$R$] Emulator system samples per frame $m_a / m_v$ \item[$R^{'}$] Estimated emulator system samples per frame $m_a^{'} / m_v^{'}$ \item[$A_b$] Current amount of samples in the audio buffer \item[$A_B$] Capacity (in samples) of the audio buffer \item[$d$] Allowed deviation in audio pitch \end{itemize} \subsection{Resampling audio} Every time the game system outputs audio, it is resampled with some ratio. It is here assumed that the game system outputs a video frame worth of audio at a time. While the formulae are invariant to how often audio is written to audio buffers, this assumption is made for simplicity. The correct resampling ratio is estimated to be $R^{'} / r$, thus pushing $R^{'}$ samples of audio per frame on average. In the duration of a frame, on average, $R$ audio frames will have been played to the speakers and thus removed from the buffer. \begin{equation} \Delta A_b = R^{'} - R \end{equation} We see that unless $\Delta A_b = 0$, it is inevitable that the audio will either underrun ($A_b \leq 0$), or block due to buffer being full ($A_b \geq A_B$). Both these situations are not acceptable as underruns would cause audible audio dropouts, and blocking would block the emulator from emulating more frames, and thus greatly increasing the chance of missing a VBlank, which is not acceptable as well. Blocking however, is far more preferable than underrunning. As with any estimator, it is impossible to guarantee that $R^{'}$ can be perfectly estimated. Therefore, it is impossible to guarantee that underrun nor blocking occurs. \subsection{Dynamic rate control} The proposed method will dynamically adjust the resampling ratio $R^{'} / r$. Changing this ratio will adjust audio pitch as well. To ensure that these adjustments are not audible to the human ear, the range of adjustment will be limited by $d$. Using $d$, the maximum pushed samples will be $R^{'} \left(1 + d\right)$, and similarly, minimum will be $R^{'} \left(1 - d\right)$. $d$ must be chosen so that $R$ falls between minimum or maximum. This depends on the confidence of the estimate $R^{'}$. The revised update formula will look like this: \begin{equation} \label{eq:update} \Delta A_b = \left[ 1 + \left(\frac{A_B - 2A_b}{A_B}\right) d \right] R^{'} - R \end{equation} The formula will decrease resampling ratio if audio buffer is over half full, and similarly increase resampling ratio if buffer is below half full. \subsection{Stability} To ensure that the method is stable, i.e. that $A_b$ will converge to a certain value, we assume a continuous model for pushing audio. \begin{equation} \frac{\delta A_b}{\delta f} = \left[ 1 + \left(\frac{A_B - 2A_b}{A_B}\right) d \right] R^{'} - R \end{equation} \begin{equation} \label{eq:ab-diff} \frac{\delta A_b}{\delta f} + \frac{2dR^{'}}{A_B}A_b = R^{'} \left(1 + d\right) - R \end{equation} The differential equation in \eqref{eq:ab-diff} can be solved as \begin{equation} A_b = A_B \frac{R^{'}\left(1 + d\right) - R}{2dR^{'}} + C_0\exp \left(-\frac{2dR^{'}}{A_B} f\right) \end{equation} Given time ($f \rightarrow \infty$), this expression converges to \begin{equation} A_{b,c} = A_B \frac{R^{'}\left(1 + d\right) - R}{2dR^{'}} \end{equation} If $R^{'}$ is the ideal estimate, $R^{'} = R$, the expression converges to \begin{equation} A_{b,c} = A_B / 2 \end{equation} which is the best case, as having a half full buffer means most possible wiggle room for jitter. \subsection{Updating ratio estimate $R^{'}$} After time, it is assumed that $A_b$ will converge to $A_{b,c}$. Due to jitter, and various non-ideal behavior, only an estimate of $A_{b,c}$, $\hat{A_{b,c}} = \bar{A_b}$ can be obtained. \begin{equation} \frac{\hat{R^{'}}}{R} = \frac{A_B}{\left(1 + d\right) A_B - 2d\hat{A_{b,c}}} \end{equation} The ratio estimate $R^{'}$ can thus be re-estimated accordingly. This method of re-estimating the ratio might however not be the best. Directly estimating $m_a^{'}$ and $m_v^{'}$ should yield more confident results, but this is outside the scope of this article. \section{Results} A synthetic test was carried out to test how the method would react to a common scenario for this method. An emulation of Super Nintendo Entertainment System (SNES) was matched to an emulating system. To test effects of jitter, the frame time was assumed to follow a normal distribution. Thus, $R$ in \eqref{eq:update} followed a normal distribution. \begin{table}[H] \centering \caption{Timings} \begin{tabular}{|c|c|c|} \hline System & FPS (Hz) & Sample rate (Hz)\\\hline SNES & 60.0988 & 32040.5\\\hline Emulating system & 59.88 & 48000.15\\\hline Estimated system & 59.95 & 48000.0\\\hline \end{tabular} \end{table} \begin{table}[H] \centering \caption{Test parameters} \begin{tabular}{|c|c|} \hline $d$ & $0.005$\\\hline Frame time deviation & $2 \%$\\\hline \end{tabular} \end{table} \begin{figure}[H] \centering \includegraphics[width=12cm]{ratecontrol-data.pdf} \caption{Results with 2\% standard deviation on frame time} \end{figure} The results are shown for audio buffer size over time and the pitch modulation for every simulated frame. Audio pitch modulation deviation was estimated to $0.062\%$, significantly lower than the $d$ value, which allowed for a maximum deviation of $0.5\%$. The audio buffer is never filled nor underrun, which would allow every single VBlank to be met, while maintaining audio sync. \section{Discussion} \subsection{Effect of $d$} Ideally, $d$ should be as low as possible to avoid large deviations in pitch, but at the same time, a too low value for $d$ will not be able to compensate for the difference between $R^{'}$ and $R$. From testing in the emulator frontend RetroArch\footnote{https://github.com/Themaister/RetroArch}, a factor of $d \geq 0.002, d \leq 0.005$ has been found to give satisfactory results. This method does not propose a method of determining the best $d$ factor. \subsection{Audibility} As audio pitch is altered, there is a question of audibility. Given a small enough $d$, it's clear that the effect would be completely inaudible as all oscillators in a DAC have tolerances and jitter to some degree. It is also reasonable to believe that some persons are able to notice a smaller $d$ than others. Some testing must be carried out to find a $d$ that is inaudible in subjective tests. \section{Conclusion} This method shows that it is possible to obtain synchronization to both VBlank and audio without having a perfect estimate of the emulating systems frequencies. As long as the estimates are reasonable close to the real values, the dynamic rate control method proposed here is able to smooth out the differences. \end{document} ================================================ FILE: archive/retroarch-cores-manual.lyx ================================================ #LyX 2.0 created this file. For more info see http://www.lyx.org/ \lyxformat 413 \begin_document \begin_header \textclass article \use_default_options true \maintain_unincluded_children false \language english \language_package default \inputencoding auto \fontencoding global \font_roman default \font_sans default \font_typewriter default \font_default_family default \use_non_tex_fonts false \font_sc false \font_osf false \font_sf_scale 100 \font_tt_scale 100 \graphics default \default_output_format default \output_sync 0 \bibtex_command default \index_command default \paperfontsize default \spacing single \use_hyperref true \pdf_title "RetroArch Cores Manual" \pdf_author "Hans-Kristian Antzen, Daniel De Matteis" \pdf_bookmarks true \pdf_bookmarksnumbered false \pdf_bookmarksopen false \pdf_bookmarksopenlevel 1 \pdf_breaklinks false \pdf_pdfborder false \pdf_colorlinks true \pdf_backref false \pdf_pdfusetitle true \papersize default \use_geometry false \use_amsmath 1 \use_esint 1 \use_mhchem 1 \use_mathdots 1 \cite_engine basic \use_bibtopic false \use_indices false \paperorientation portrait \suppress_date false \use_refstyle 1 \index Index \shortcut idx \color #008000 \end_index \secnumdepth 5 \tocdepth 5 \paragraph_separation indent \paragraph_indentation default \quotes_language english \papercolumns 1 \papersides 1 \paperpagestyle default \tracking_changes false \output_changes false \html_math_output 0 \html_css_as_file 0 \html_be_strict false \end_header \begin_body \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename retroarch-android/logo.png lyxscale 50 scale 50 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Title RetroArch Android (v0.9.8.4) - Cores Manual \end_layout \begin_layout Author Hans Kristian Arntzen, Daniel De Matteis \end_layout \begin_layout Standard \begin_inset CommandInset toc LatexCommand tableofcontents \end_inset \end_layout \begin_layout Section Introduction \end_layout \begin_layout Standard Listed below are all the cores that RetroArch Android supports. \end_layout \begin_layout Itemize SNES9x Next \begin_inset Newline newline \end_inset Used for: playing SNES games (Super Nintendo Entertainment System) \begin_inset Newline newline \end_inset Author(s): SNES9x team, OV2, Bearoso, zones, Squarepusher (fork) \begin_inset Newline newline \end_inset Recommended system requirements: ARM Cortex A9 multi-core device (and up) \begin_inset Newline newline \end_inset Extensions: "smc|fig|sfc|gd3|gd7|dx2|bsx|swc|zip|SMC|FIG| \begin_inset Newline newline \end_inset SFC|BSX|GD3|GD7|DX2|SWC|ZIP" \end_layout \begin_layout Itemize VBA Next \begin_inset Newline newline \end_inset Used for: playing Game Boy Advance games \begin_inset Newline newline \end_inset Recommended system requirements: ARM Cortex A9 multi-core based device (and up) \begin_inset Newline newline \end_inset Author(s): Forgotten, VBA-M team, Squarepusher (fork) \begin_inset Newline newline \end_inset Extensions: "gba|GBA|zip|ZIP" \end_layout \begin_layout Itemize FCEUmm \begin_inset Newline newline \end_inset Used for: playing NES games (Nintendo Entertainment System) \begin_inset Newline newline \end_inset Author(s): CaH4e3, original FCEU authors \begin_inset Newline newline \end_inset Extensions: "fds|FDS|zip|ZIP|nes|NES|unif|UNIF" \end_layout \begin_layout Itemize NEStopia \begin_inset Newline newline \end_inset Used for: playing NES games (Nintendo Entertainment System) \begin_inset Newline newline \end_inset Author(s): Marty \begin_inset Newline newline \end_inset Extensions supported: "nes|NES|zip|ZIP|fds|FDS" \end_layout \begin_layout Itemize Gambatte \begin_inset Newline newline \end_inset Used for: playing GameBoy / GameBoy Color games \begin_inset Newline newline \end_inset Author(s): Sinamas \begin_inset Newline newline \end_inset Extensions supported: "gb|gbc|dmg|zip|GB|GBC|DMG|ZIP" \end_layout \begin_layout Itemize Final Burn Alpha \begin_inset Newline newline \end_inset Used for: playing arcade games \begin_inset Newline newline \end_inset Author(s): Dave, FBA Team (Barry Harris & co) \begin_inset Newline newline \end_inset Extensions supported: \begin_inset Quotes eld \end_inset zip|ZIP \begin_inset Quotes erd \end_inset \end_layout \begin_layout Itemize Genesis Plus GX \begin_inset Newline newline \end_inset Used for: playing Sega Genesis / Master System / Game Gear / Sega CD games \begin_inset Newline newline \end_inset Author(s): Charles McDonald, ekeeke \begin_inset Newline newline \end_inset Extensions supported: "md|smd|bin|cue|gen|zip|MD|SMD|bin|iso| \begin_inset Newline newline \end_inset ISO|CUE|GEN|ZIP|sms|SMS|gg|GG|sg|SG" \end_layout \begin_layout Itemize NX Engine \begin_inset Newline newline \end_inset Used for: playing Cave Story / Doukutsu Monogatari \begin_inset Newline newline \end_inset Author(s): Caitlin Shaw (rogueeve) \begin_inset Newline newline \end_inset Extensions supported: \begin_inset Quotes eld \end_inset exe|EXE|zip|ZIP \begin_inset Quotes erd \end_inset \end_layout \begin_layout Itemize PCSX ReARMed \begin_inset Newline newline \end_inset Used for: playing PlayStation1 games \begin_inset Newline newline \end_inset Author(s): PCSX Team, Notaz, Exophase (GPU plugin) \begin_inset Newline newline \end_inset Extensions supported: "bin|cue|img|mdf|pbp|cbn" \end_layout \begin_layout Itemize Prboom \begin_inset Newline newline \end_inset Used for: playing Doom, Doom 2, Ultimate Doom, Final Doom, and mods \begin_inset Newline newline \end_inset Author(s): Various \begin_inset Newline newline \end_inset Extensions supported: "WAD|wad|IWAD|iwad" \end_layout \begin_layout Itemize Mednafen NGP \begin_inset Newline newline \end_inset Used for: playing Neo Geo Pocket Color games \begin_inset Newline newline \end_inset Author(s): Original Neopop authors, Ryphecha \begin_inset Newline newline \end_inset Extensions supported: "ngp|NGP|ngc|NGC|zip|ZIP" \end_layout \begin_layout Itemize Mednafen WonderSwan \begin_inset Newline newline \end_inset Used for: playing WonderSwan / WonderSwan Color / WonderSwan Crystal games \begin_inset Newline newline \end_inset Author(s): Original Cygne authors, Ryphecha \begin_inset Newline newline \end_inset Extensions supported: "ws|WS|wsc|WSC|zip|ZIP" \end_layout \begin_layout Itemize Mednafen Virtual Boy \begin_inset Newline newline \end_inset Used for: playing Virtual Boy games \begin_inset Newline newline \end_inset Author: Ryphecha \begin_inset Newline newline \end_inset Extensions supported: "vb|VB|vboy|VBOY|bin|BIN|zip|ZIP" \end_layout \begin_layout Itemize Mednafen PC Engine \begin_inset Newline newline \end_inset Used for: playing PC Engine / Supergrafx 16 / PC Engine CD games \begin_inset Newline newline \end_inset Author: Ryphecha \begin_inset Newline newline \end_inset Extensions supported: "pce|PCE|sgx|SGX|cue|CUE|zip|ZIP" \end_layout \begin_layout Standard We'll go over each of these. \end_layout \begin_layout Subsection SNES9x Next \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Version:} \end_layout \end_inset v1.52.3 \begin_inset Newline newline \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Android performance:} \end_layout \end_inset This emulator should run at fullspeed on an Android device with a dual-core ARM Cortex A9-based CPU. \end_layout \begin_layout Subsubsection CHANGELOG \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{v1.52.4} \end_layout \end_inset \end_layout \begin_layout Itemize Speed optimizations for Star Fox 1 / Star Wing - now makes them fast enough for fullspeed gameplay on Wii. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{v1.52.3} \end_layout \end_inset \end_layout \begin_layout Itemize Fixed DKC2 graphics inaccuracies \end_layout \begin_layout Itemize Fixed issue that could corrupt memory addresses over time - found while deiniting Super Mario Kart. \end_layout \begin_layout Itemize Updated to use RGB565 as pixel format. \end_layout \begin_layout Itemize Speed hacks for Final Fantasy III/VI - makes it fullspeed for Wii. \end_layout \begin_layout Itemize Fixed Super Double Dragon input issue. \end_layout \begin_layout Subsection VBA Next \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Version:} \end_layout \end_inset v1.0.2 \begin_inset Newline newline \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Android performance:} \end_layout \end_inset This emulator needs at least a dual-core ARM Cortex A9-based CPU and up. \end_layout \begin_layout Subsubsection CHANGELOG \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{v1.0.2} \end_layout \end_inset \end_layout \begin_layout Itemize Added Pokemon Emerald to built-in vbaover - fixes white screen \end_layout \begin_layout Itemize Lessens RAM footprint - makes Mother 3 fit into memory on Wii. \end_layout \begin_layout Itemize More consistent syncing. \end_layout \begin_layout Itemize Updated to use RGB565 as pixel format. \end_layout \begin_layout Subsection FCEUmm \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Version:} 98.13 SVN \end_layout \end_inset \begin_inset Newline newline \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Android performance:} \end_layout \end_inset This emulator has been tested to run at fullspeed on an ARM Cortex A8 single-co re CPU. Your mileage may vary on slower devices. \end_layout \begin_layout Subsubsection CHANGELOG \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{For 0.9.8 point release} \end_layout \end_inset \end_layout \begin_layout Itemize Upgraded to latest SVN (r134) \end_layout \begin_layout Itemize Updated to use RGB565 as pixel format. \end_layout \begin_layout Subsection NEStopia \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Version:} 1.44 \end_layout \end_inset \begin_inset Newline newline \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Android performance:} \end_layout \end_inset This emulator has been tested to run at fullspeed on an ARM Cortex A8 single-co re CPU. Your mileage may vary on slower devices. \end_layout \begin_layout Subsubsection NOTES \end_layout \begin_layout Itemize There might still be an audio desync that happen at the half hour mark. Ever since NEStopia 1.36 some kind of APU bug has been inadvertently introduced. We will be researching this. \end_layout \begin_layout Itemize For Famicom Disk System games - Y Button will switch sides of a disk. - If you get any problems of the sort DISK A / B ERR 07' - pressing Y button again or letting it run its course should do it. \end_layout \begin_layout Itemize Famicom Disk System loading is slow, so you might be tempted to fast forward through most of it. However, I'd advise caution when doing so and to savestate regularly in case 'fast forwarding' can negatively affect disk loading. \end_layout \begin_layout Subsubsection CHANGELOG \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{For 0.9.8.3 point release} \end_layout \end_inset \end_layout \begin_layout Itemize Famicom Disk System support. For Android users - put disksys.rom into the same folder as the FDS ROM you're trying to load. For everyone else - put disksys.rom into your system directory. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{For 0.9.8 point release} \end_layout \end_inset \end_layout \begin_layout Itemize New port \end_layout \begin_layout Subsection Gambatte \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Version:} 0.50 \end_layout \end_inset \begin_inset Newline newline \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Android performance:} \end_layout \end_inset This emulator has been tested to run at fullspeed on an ARM Cortex A8 single-co re CPU. Your mileage may vary on slower devices. \end_layout \begin_layout Subsubsection CHANGELOG \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{For 0.9.8 point release} \end_layout \end_inset \end_layout \begin_layout Itemize Now makes use of GBC BIOS color palettes. \end_layout \begin_layout Itemize Can also make use of custom color palettes. \end_layout \begin_layout Itemize Updated to use RGBX8888 as pixel format. \end_layout \begin_layout Subsection Final Burn Alpha \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Version:} 0.2.97.28 \end_layout \end_inset \begin_inset Newline newline \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Android performance:} \end_layout \end_inset Performance varies based on the game you're trying to play. Systems like CPS2 and Neogeo have been tested to run at fullspeed on an ARM Cortex A8 single-core CPU. CPS3 needs a dual-core ARM Cortex A9-based CPU for fullspeed gameplay. Your mileage may vary on slower devices. \end_layout \begin_layout Subsubsection NOTES \end_layout \begin_layout Itemize Some games might be stuck in Service mode right now on big-endian systems (ie. PS3/360/Wii). Some games that come to mind are Psikyo SH2 games and Taito games like Darius 2. We will be trying to fix this issue soon and release a point update for it. \end_layout \begin_layout Itemize Button combos ingame: \end_layout \begin_layout Itemize RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Select = Service Menu button \begin_inset Newline newline \end_inset RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Start = Diagnostic button \begin_inset Newline newline \end_inset RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Left = Reset button \begin_inset Newline newline \end_inset RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Right = DIP A Pressed \begin_inset Newline newline \end_inset RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Up = DIP B Pressed \begin_inset Newline newline \end_inset RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Down = Test Pressed \end_layout \begin_layout Itemize Savestates are hooked up but games can't have their 'state restored' after unloading the game and loading it again. \end_layout \begin_layout Itemize If you want to play Warzard or Red Earth and you happen to get a 'No CD-ROM drive' message - do the 'Reset' combo (see above) - it should work then. \end_layout \begin_layout Subsubsection CHANGELOG \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{For 0.9.8 point release} \end_layout \end_inset \end_layout \begin_layout Itemize Upgraded to 0.2.97.28. \end_layout \begin_layout Itemize Controls have been revised - most of the controls should now be properly hooked up. \end_layout \begin_layout Itemize Button combos have been changed - \begin_inset Newline newline \end_inset RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Select = Service Menu button \begin_inset Newline newline \end_inset RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Start = Diagnostic button \begin_inset Newline newline \end_inset RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Left = Reset button \begin_inset Newline newline \end_inset RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Right = DIP A Pressed \begin_inset Newline newline \end_inset RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Up = DIP B Pressed \begin_inset Newline newline \end_inset RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Down = Test Pressed \end_layout \begin_layout Itemize Uses RGBX8888 as a color format for Psikyo SH2 games and RGB565 for everything else. \end_layout \begin_layout Subsection Genesis Plus GX \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Version:} 1.7.3 \end_layout \end_inset \begin_inset Newline newline \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Android performance:} \end_layout \end_inset This emulator has been tested to run regular Genesis and Sega CD games at fullspeed on an ARM Cortex A8 single-core CPU. Virtua Racing runs at half realtime speed on the same hardware and thus needs better system requirements. Your mileage may vary on slower devices. \end_layout \begin_layout Subsubsection NOTES \end_layout \begin_layout Itemize FOR ANDROID: To play Sega CD/Mega CD games, you will need Sega CD BIOS files in the same directory as the game you want to play. They should be named as follows: bios_CD_E.bin (for EU BIOS), bios_CD_U.bin (for US BIOS), bios_CD_J.bin (for Japanese BIOS) \end_layout \begin_layout Itemize FOR EVERYTHING ELSE: To play Sega CD/Mega CD games, you will need Sega CD BIOS files in the same directory as the game you want to play. They should be named as follows: bios_CD_E.bin (for EU BIOS), bios_CD_U.bin (for US BIOS), bios_CD_J.bin (for Japanese BIOS). \end_layout \begin_layout Subsubsection CHANGELOG \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{For 0.9.8 point release} \end_layout \end_inset \end_layout \begin_layout Itemize Upgraded to 1.7.3 ( might report 1.7.1 but is really 1.7.3). \end_layout \begin_layout Itemize Updated to use RGB565. \end_layout \begin_layout Subsection NX Engine \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Version:} 1.0.4 \end_layout \end_inset \begin_inset Newline newline \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Android performance:} \end_layout \end_inset This game has been tested to run at fullspeed on an ARM Cortex A8 single-core CPU. Sound syncing however is currently not correct. Your mileage may vary on slower devices. \end_layout \begin_layout Subsubsection HOW TO USE \end_layout \begin_layout Standard You need to copy all the 'datafiles' directory in the repository over. Start the core with doukutsu.exe - it should properly extract the needed archives from the EXE on initial boot. From there on it will use those extracted asset files. \end_layout \begin_layout Subsubsection NOTES \end_layout \begin_layout Itemize NXEngine is not released yet on consoles - sound is currently corrupt on big-endian consoles (Xbox 1/360/PS3/Wii). Will need to research what is up here. \end_layout \begin_layout Itemize Savestates are not hooked up - therefore rewind is also not possible. \end_layout \begin_layout Subsubsection CHANGELOG \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{For 0.9.8 point release} \end_layout \end_inset \end_layout \begin_layout Itemize Upgraded to 1.0.4. \end_layout \begin_layout Itemize Did major changes to path handling code and got rid of the hardcoded paths - should now handle paths correctly on _WIN32 targets. \end_layout \begin_layout Itemize Fixed save files not working. \end_layout \begin_layout Itemize Updated to use RGB565. \end_layout \begin_layout Subsection PCSX ReARMed \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Version:} r18 \end_layout \end_inset \begin_inset Newline newline \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Android performance:} \end_layout \end_inset This emulator has been tested to run most games at fullspeed on an ARM Cortex A8 single-core CPU. Higher-resolution interlaced games like Tekken 3 and Tobal 2 require higher system specs (Cortex A9 and up). Your mileage may vary on slower devices. \end_layout \begin_layout Subsubsection NOTES \end_layout \begin_layout Itemize PCSX ReARMed supports the loading of EBOOT (pbp) files as well. \end_layout \begin_layout Itemize Although PCSX ReARMed comes with built-in HLE BIOS code, you're recommended to still put BIOS files in the system directory (on Android there is no 'system directory', so instead you put the BIOS files in the same directory as the image you're trying to load). Some of the BIOS files used are: scph1001.bin, scph5500.bin, scph5501.bin, scph5502.bin, scph7502.bin. \end_layout \begin_layout Itemize If an image might not load correctly, try it with and without BIOS files in the 'system directory' (read above note about 'system directory' as well). \end_layout \begin_layout Itemize This is an ARM architecture-centric port right now - it is not of much use on other architectures and therefore consoles. \end_layout \begin_layout Subsubsection CHANGELOG \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{For 0.9.8 point release} \end_layout \end_inset \end_layout \begin_layout Itemize New port. \end_layout \begin_layout Subsection Prboom \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Version:} 2.5.0 \end_layout \end_inset \begin_inset Newline newline \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Android performance:} \end_layout \end_inset This game engine has been tested to run most games at fullspeed on an ARM Cortex A8 single-core CPU. Your mileage may vary on slower devices. \end_layout \begin_layout Subsubsection NOTES \end_layout \begin_layout Itemize You need to have prboom.wad in the same directory as the Doom WAD file you're going to load. \end_layout \begin_layout Itemize Savestates are currently not hooked up, and therefore rewind is not possible. \end_layout \begin_layout Itemize Re-entrancy does not work correctly yet - don't try to load a second WAD file. Instead, exit prboom first and then launch it again (only applies to consoles). \end_layout \begin_layout Itemize This is the only Doom port in existence right now where you have the option to play at variable framerates. The option exists to play at 35, 40, 50 and 60fps. Doom originally ran at 35fps due to performance reasons and the slow CPUs available at the time. \end_layout \begin_layout Subsubsection CHANGELOG \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{For 0.9.8 point release} \end_layout \end_inset \end_layout \begin_layout Itemize Now uses RGB565 as pixel format. \end_layout \begin_layout Subsubsection SOUNDTRACK LIST \end_layout \begin_layout Standard Prboom supports MP3 soundtracks. The files must be in the same directory as the WAD file and should be correctly named. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{ \backslash break} \end_layout \end_inset \end_layout \begin_layout Standard DOOM 1 \end_layout \begin_layout Standard e1m1.mp3 \end_layout \begin_layout Standard e1m2.mp3 \end_layout \begin_layout Standard e1m3.mp3 \end_layout \begin_layout Standard e1m4.mp3 \end_layout \begin_layout Standard e1m5.mp3 \end_layout \begin_layout Standard e1m6.mp3 \end_layout \begin_layout Standard e1m7.mp3 \end_layout \begin_layout Standard e1m8.mp3 \end_layout \begin_layout Standard e1m9.mp3 \end_layout \begin_layout Standard e2m1.mp3 \end_layout \begin_layout Standard e2m2.mp3 \end_layout \begin_layout Standard e2m3.mp3 \end_layout \begin_layout Standard e2m4.mp3 \end_layout \begin_layout Standard e2m5.mp3 \end_layout \begin_layout Standard e2m6.mp3 \end_layout \begin_layout Standard e2m7.mp3 \end_layout \begin_layout Standard e2m8.mp3 \end_layout \begin_layout Standard e2m9.mp3 \end_layout \begin_layout Standard e3m1.mp3 \end_layout \begin_layout Standard e3m2.mp3 \end_layout \begin_layout Standard e3m3.mp3 \end_layout \begin_layout Standard e3m4.mp3 \end_layout \begin_layout Standard e3m5.mp3 \end_layout \begin_layout Standard e3m6.mp3 \end_layout \begin_layout Standard e3m7.mp3 \end_layout \begin_layout Standard e3m8.mp3 \end_layout \begin_layout Standard intermid1.mp3 \end_layout \begin_layout Standard intro.mp3 \end_layout \begin_layout Standard bunny.mp3 \end_layout \begin_layout Standard victor.mp3 \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{ \backslash break} \end_layout \end_inset \end_layout \begin_layout Standard DOOM 2 \end_layout \begin_layout Standard stalks.mp3 \end_layout \begin_layout Standard runnin.mp3 \end_layout \begin_layout Standard countd.mp3 \end_layout \begin_layout Standard betwee.mp3 \end_layout \begin_layout Standard doom.mp3 \end_layout \begin_layout Standard the_da.mp3 \end_layout \begin_layout Standard shawn.mp3 \end_layout \begin_layout Standard ddtblu.mp3 \end_layout \begin_layout Standard in_cit.mp3 \end_layout \begin_layout Standard dead.mp3 \end_layout \begin_layout Standard romero.mp3 \end_layout \begin_layout Standard messag.mp3 \end_layout \begin_layout Standard ampie.mp3 \end_layout \begin_layout Standard tense.mp3 \end_layout \begin_layout Standard openin.mp3 \end_layout \begin_layout Standard evil.mp3 \end_layout \begin_layout Standard ultima.mp3 \end_layout \begin_layout Standard read_m.mp3 \end_layout \begin_layout Standard dm2ttl.mp3 \end_layout \begin_layout Standard dm2int.mp3 \end_layout \begin_layout Subsection Mednafen NGP \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Version:} 0.9.28 \end_layout \end_inset \begin_inset Newline newline \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Android performance:} \end_layout \end_inset This emulator has been tested to run at fullspeed on an ARM Cortex A8 single-co re CPU. Your mileage may vary on slower devices. \end_layout \begin_layout Subsubsection CHANGELOG \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{For 0.9.8 point release} \end_layout \end_inset \end_layout \begin_layout Itemize New port. \end_layout \begin_layout Subsection Mednafen Wonderswan \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Version:} 0.9.28 \end_layout \end_inset \begin_inset Newline newline \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Android performance:} \end_layout \end_inset This emulator has been tested to run at fullspeed on an ARM Cortex A8 single-co re CPU. Your mileage may vary on slower devices. \end_layout \begin_layout Subsubsection NOTES \end_layout \begin_layout Itemize The music is incorrect on Xbox 360. This seems to be a 360-specific bug. \end_layout \begin_layout Itemize Because Wonderswan has a 75Hz refresh rate, V-sync is specifically disabled for this core so that the framerate and sound is as it should be - that's why you might notice some negligible tearing. \end_layout \begin_layout Subsubsection CHANGELOG \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{For 0.9.8 point release} \end_layout \end_inset \end_layout \begin_layout Itemize Upgraded to 0.9.28 version. \end_layout \begin_layout Itemize Fixes save file issues on MSVC-based consoles (Xbox 1/360). \end_layout \begin_layout Itemize Now uses RGB565 as a pixel format. \end_layout \begin_layout Subsection Mednafen Virtual Boy \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Version:} 0.9.28 \end_layout \end_inset \begin_inset Newline newline \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Android performance:} \end_layout \end_inset You will need at least a Cortex A9 CPU and/or higher for this. \end_layout \begin_layout Subsubsection NOTES \end_layout \begin_layout Itemize This is not released yet for Xbox 1 and 360 because there are numerous game compatibility-breaking issues right now. \end_layout \begin_layout Subsubsection CHANGELOG \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{For 0.9.8 point release} \end_layout \end_inset \end_layout \begin_layout Itemize New port. \end_layout \begin_layout Subsection Mednafen PC Engine \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Version:} 0.9.28 \end_layout \end_inset \begin_inset Newline newline \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Android performance:} \end_layout \end_inset This emulator has been tested to run at fullspeed on an ARM Cortex A8 single-co re CPU. Your mileage may vary on slower devices. \end_layout \begin_layout Subsubsection NOTES \end_layout \begin_layout Itemize FOR ANDROID USERS: \begin_inset space ~ \end_inset You will need a BIOS file called 'syscard3.pce' placed in the same directory as the ISO/CUE you want to play to be able to play PC Engine CD games. \end_layout \begin_layout Itemize FOR ANYBODY ELSE: You will need a BIOS file called 'syscard3.pce' in your system directory in order to be able to play PC Engine CD games. \end_layout \begin_layout Subsubsection CHANGELOG \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{For 0.9.8 point release} \end_layout \end_inset \end_layout \begin_layout Itemize Upgraded to 0.9.28. \end_layout \begin_layout Itemize Fixes save file issues on MSVC-based consoles (Xbox 1/360). \end_layout \begin_layout Itemize Updated to use RGB565 as pixel format. \end_layout \begin_layout Section About Us \end_layout \begin_layout Standard Homepage: \begin_inset Flex URL status collapsed \begin_layout Plain Layout http://www.libretro.org \end_layout \end_inset \begin_inset Newline newline \end_inset IRC: #retroarch at freenode \begin_inset Newline newline \end_inset Github (libretro organization): \begin_inset Flex URL status collapsed \begin_layout Plain Layout https://github.com/libretro \end_layout \end_inset \begin_inset Newline newline \end_inset RetroArch @ Github: \begin_inset Flex URL status collapsed \begin_layout Plain Layout https://github.com/Themaister/RetroArch \end_layout \end_inset \begin_inset Newline newline \end_inset Libretro @ Twitter: \begin_inset Flex URL status collapsed \begin_layout Plain Layout https://twitter.com/libretro \end_layout \end_inset \begin_inset Newline newline \end_inset Libretro @ Facebook: \begin_inset Flex URL status collapsed \begin_layout Plain Layout https://www.facebook.com/libretro.retroarch \end_layout \end_inset \end_layout \end_body \end_document ================================================ FILE: archive/retroarch-enduserguide.lyx ================================================ #LyX 2.0 created this file. For more info see http://www.lyx.org/ \lyxformat 413 \begin_document \begin_header \textclass article \use_default_options true \maintain_unincluded_children false \language english \language_package default \inputencoding auto \fontencoding global \font_roman default \font_sans default \font_typewriter default \font_default_family default \use_non_tex_fonts false \font_sc false \font_osf false \font_sf_scale 100 \font_tt_scale 100 \graphics default \default_output_format default \output_sync 0 \bibtex_command default \index_command default \paperfontsize default \spacing single \use_hyperref true \pdf_title "RetroArch End-user Guide" \pdf_bookmarks true \pdf_bookmarksnumbered false \pdf_bookmarksopen false \pdf_bookmarksopenlevel 1 \pdf_breaklinks false \pdf_pdfborder false \pdf_colorlinks true \pdf_backref false \pdf_pdfusetitle true \papersize default \use_geometry false \use_amsmath 1 \use_esint 1 \use_mhchem 1 \use_mathdots 1 \cite_engine basic \use_bibtopic false \use_indices false \paperorientation portrait \suppress_date false \use_refstyle 1 \index Index \shortcut idx \color #008000 \end_index \secnumdepth 5 \tocdepth 5 \paragraph_separation indent \paragraph_indentation default \quotes_language english \papercolumns 1 \papersides 1 \paperpagestyle default \tracking_changes false \output_changes false \html_math_output 0 \html_css_as_file 0 \html_be_strict false \end_header \begin_body \begin_layout Title RetroArch End-User Guide \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Part* Welcome to RetroArch! \end_layout \begin_layout Standard RetroArch does things differently from other programs. In this guide, you will learn what RetroArch is, how it works and the various things you can do with it as an end-user. \end_layout \begin_layout Standard This guide is aimed at the end-user. It does not intend to be a comprehensive reference for anything and everything to do with the libretro project and/or RetroArch. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Standard \begin_inset CommandInset toc LatexCommand tableofcontents \end_inset \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Part What is RetroArch? \end_layout \begin_layout Standard RetroArch is a cross platform architecture that aims to become a 'one-stop shop' for emulators, videogames, multimedia, augmented reality and other areas of interest. It manages to do all of these things by implementing a specification known as the libretro API (Application Programming Interface). \end_layout \begin_layout Standard Libretro is a powerful interface that allows you to port applications to the spec and be able to run them on any libretro-compatible client in existence. \end_layout \begin_layout Standard RetroArch is the 'official' libretro client. Right now it is available on many platforms and it aims to deliver the most optimal performance possible on a given host platform. You will generally find that RetroArch will be first in implementing new features and/or additions that get added to the libretro interface. \end_layout \begin_layout Standard RetroArch is most well known for an entire suite of emulators that have been ported to the libretro specification and are therefore able to be run in RetroArch. Therefore, it has been compared in the media to other multi-system emulators, such as OpenEmu, and/or MESS. Note that we don't particularly approve of this attempt to pigeonhole RetroArch - we don't think of libretro and/or RetroArch as being limited to emulators, or even games for that matter. \end_layout \begin_layout Standard Over the next few months the distinction between RetroArch and these types of programs will start becoming more and more apparent. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Part What platforms can I use RetroArch on? \end_layout \begin_layout Standard Being on every system anywhere is the most important goal of RetroArch. Therefore, it is available for many platforms - for free. The program (except for minor cosmetic differences per version) should behave more or less exactly the same from one platform to another. \end_layout \begin_layout Standard The list of available devices and/or operating systems include: \end_layout \begin_layout Itemize PC (Microsoft Windows XP/Vista/7/8/8.1) \end_layout \begin_layout Itemize Mac (OSX Snow Leopard [10.6.8] up to Mavericks [10.9]) \end_layout \begin_layout Itemize Linux \end_layout \begin_layout Itemize Android (version 2.3 and higher) \end_layout \begin_layout Itemize iOS (version 6.0 and higher [*]) \end_layout \begin_layout Itemize Blackberry Playbook \end_layout \begin_layout Itemize Blackberry 10 \end_layout \begin_layout Itemize PlayStation3 [*] \end_layout \begin_layout Itemize Nintendo Wii [*] \end_layout \begin_layout Itemize Nintendo GameCube [*] \end_layout \begin_layout Itemize Microsoft Xbox [*] \end_layout \begin_layout Itemize Microsoft Xbox 360 [*] \end_layout \begin_layout Itemize Browser / Javascript (Emscripten) \end_layout \begin_layout Standard Some of the systems listed above (the ones marked [*]) might require a jailbreak or a modification of some sort so that RetroArch is able to run on it. This is something you will have to figure out on your own and for which we provide no support or help at all. \end_layout \begin_layout Standard For the latest versions, go to the official homepage - \begin_inset Flex URL status open \begin_layout Plain Layout http://www.libretro.com \end_layout \end_inset , and click on the platform you want to download a copy of RetroArch for. \end_layout \begin_layout Standard In the future, RetroArch will be ported to even more systems. The aim for RetroArch is to have a program that will be able to run on as many platforms as possible, and bringing along with it all the libretro cores that RetroArch (as a libretro client) is able to run. \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Part How does RetroArch work? \end_layout \begin_layout Standard RetroArch is a plugin-driven application. Every program that you can run in RetroArch is a plugin that gets loaded by RetroArch on-the-fly. We refer to these plugin cores from this point on as 'libretro cores'. \end_layout \begin_layout Standard A libretro core is an app implementing the libretro specification packaged as a plugin. The 'libretro core' defines the 'behavior' of what RetroArch will do, since RetroArch by itself does nothing. So, a core can turn RetroArch into a videogame emulator, a game, a movie player, etc. It's up to what the developer wants the libretro core to do. \end_layout \begin_layout Standard Through this model, apps implementing the libretro specification form part of a larger ecosystem that every libretro-compatible client will be able to tap into. Libretro's aim is to make convergence possible - so that you can run an app on one system, then run it on another system, or play in a browser and then continue and pick up where you left off by launching the same app from your mediaplayer. \end_layout \begin_layout Standard RetroArch can be thought of as the 'Proof of Concept' that demonstrates that this kind of convergence is possible. Other apps (media players, multi-system emus, CAD applications) are encouraged and allowed to implement the specification themselves. \end_layout \begin_layout Standard The user can do many things with RetroArch, from playing games to watching movies (and other activities in the near future). The user is in control of what he wants to turn RetroArch into, for what purposes it will be used and what content will be run in it. There is no digital rights management or restrictions imposed upon the user. \end_layout \begin_layout Standard A brief summary of all available 'libretro cores' so far will be provided at the end of this guide. \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Part How do you control RetroArch? \end_layout \begin_layout Standard RetroArch (and libretro as a result) has been designed around one common input device - something we call the 'RetroPad'. You use this input device for controlling all aspects of RetroArch - from the game to the RetroArch system menus. \end_layout \begin_layout Standard The RetroPad is a traditional videogame controller of the Nintendo/Sony mould. It has a D-pad, a Start/Select button, four face buttons, up to 4 shoulder buttons/triggers, and (optional) two analog sticks. \end_layout \begin_layout Standard Unlike other apps, RetroArch is designed to be controlled with a gamepad as its primary input. We want to deliver a user experience that is as close to a traditional videogame console as possible, and to that end, we believe having to jockey between a keyboard, a mouse, and/or a gamepad/mouse is a bad user experience - when you could all do it with your gamepad anyway. \end_layout \begin_layout Standard The RetroPad is an 'abstraction' - when you run RetroArch, your own gamepad (or keyboard/touch overlay) will have a 1-to-1 mapping to this 'RetroPad' abstraction. You map your input device of choice to all the buttons and triggers that the RetroPad supports, and from there on you can control RetroArch's built-in menu system \begin_inset Foot status collapsed \begin_layout Plain Layout On tablets and phones, you can interact with the upper-layer system menus through touch \end_layout \end_inset . \end_layout \begin_layout Standard The mobile ports (because of touch being the primary input device) are controlle d using a graphical overlay of the RetroPad that gets pasted on top of the screen. This overlay can be interacted with through touch, and it's possible to switch between different 'pages' of the overlay - and to switch overlays on-the-fly. \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Part How do I go to the built-in UI? \end_layout \begin_layout Standard RetroArch has a built-in UI (User Interface) that functions nearly the same across every platform. It is called RGUI (short for Retro GUI). Most of RetroArch's features can be changed on-the-fly from this. \end_layout \begin_layout Standard Just like everything else in RetroArch, RGUI is controlled with the RetroPad. Like the name suggests, it is a no-frills User Interface that is not big on eye-candy. On the plus side, it is very scaleable and works well even at resolutions as low as 320x240. \end_layout \begin_layout Standard The user has two ways to bring up this menu: \end_layout \begin_layout Itemize Button bind - most RetroArch versions allow you to bind 'Toggle Menu' to a key/button on your input device. By pressing this button/key, you can toggle the built-in UI on or off. \end_layout \begin_layout Itemize Overlay - An overlay usually contains a button with a 'space invaders' icon in it. Touching this button will toggle the built-in UI on or off. \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Part How do I load content in RetroArch? \end_layout \begin_layout Standard A version of RetroArch typically has three ways to load content. You can select these options from the built-in UI. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Load Content (History):} \end_layout \end_inset You can select from a list of previously loaded content here. All the content you have ran in RetroArch will be added to this list. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Load Content (Detect Core):} \end_layout \end_inset You can select a file from the filebrowser. It will try to detect if a core has been installed that supports the extension of the file you just selected. If it finds only one core that supports this file extension, it will autostart that core with the chosen content immediately. If it finds multiple cores that supports this file extension,it will let you choose from a list of supported cores. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Load Content:} \end_layout \end_inset You can select a file from the filebrowser, and it will be started with the currently selected 'core'. In order to change the core currently being selected, you have to select another one from 'Load Core'. \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Part Listing of available cores \end_layout \begin_layout Standard The number of plugin cores that get added to the libretro ecosystem keeps increasing. Covering all of these would fall outside the scope of this guide, so we're only going to cover a few ones in more detail. \end_layout \begin_layout Standard We try to make an effort to have a core run on as many systems as possible. Unfortunately, there will always be instances where a core is not available for a specific platform. \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Section bsnes \end_layout \begin_layout Standard This is a Super Nintendo emulator based on the open-source emulator bsnes. It is an accuracy-focused emulator and as such can run almost all games for the SNES with cycle accuracy, unlike other SNES emulators. However, this comes at the cost of performance. \end_layout \begin_layout Subsection How to run \end_layout \begin_layout Standard bSNES does not work on its own, but runs SNES ROM images. These image files need to have the following extensions \end_layout \begin_layout Itemize sfc \end_layout \begin_layout Standard Select one of these. If the image is verified to be OK, it will start up the game. \end_layout \begin_layout Subsection How do all these different versions compare? \end_layout \begin_layout Standard There are several versions of bsnes out there. \end_layout \begin_layout Subsubsection bsnes Performance v0.92 \end_layout \begin_layout Standard This is a fairly recent version of bsnes' performance core - the same one used in Higan. Some games - like Mega Man X2 and X3 - are broken with this version even if you have the BIOS files placed in your System directory. Some of the games requiring high accuracy won't run correctly either. To make up for it, it has much better performance than the balanced or accuracy cores. \end_layout \begin_layout Subsubsection bsnes Balanced v0.92 \end_layout \begin_layout Standard This is a fairly recent version of bsnes' performance core - the same one used in Higan. It should play games like Mega Man X2/X3 with no problems. It is much slower than bsnes performance but still a lot faster than bsnes accuracy. \end_layout \begin_layout Subsubsection bsnes Accuracy v0.92 \end_layout \begin_layout Standard This is a fairly recent version of bsnes' accuracy core - the same one used in Higan. This should be capable of playing all SNES games accurately at the cost of performance. \end_layout \begin_layout Subsubsection bsnes Performance C++98 v0.85 \end_layout \begin_layout Standard Later versions of bsnes are written in cutting-edge C++11 and cannot be used on certain outdated compilers. This port of bsnes to C++98 was written for those compilers in mind. It is an older version of bsnes compared to the one in Higan but there should only be minor differences between this and bsnes performance v0.92. \end_layout \begin_layout Subsection Libretro port-specific additions \end_layout \begin_layout Subsubsection Cartridge folders not enforced \end_layout \begin_layout Standard Cartridge folders are not forced on you, and you are still able to load SFC ROMs without having to go the Purify route. \end_layout \begin_layout Subsubsection More pragmatic static syncing \end_layout \begin_layout Standard Higan's way of static synchronization is for all intents and purposes like RetroArch's, except ours is superior from an end-user point of view. It does not require of the user that he has to dial a figurative knob for hours on end to get the 'perfect refresh rate' of his monitor as a reference clock for the emulator - instead, it only requires that the app refresh rate you use is close enough to the refresh rate of your screen. From there on, dynamic rate control picks up the slack for whenever audio is running late, and combined with threaded video this allows highly demanding and sync-heavy cores like bsnes to run tolerably even on a very high-latency OS like Android. \end_layout \begin_layout Subsection Known issues \end_layout \begin_layout Subsubsection Mega Man X2/X3 don't run with bsnes performance core \end_layout \begin_layout Standard This is a known issue and it's unlikely byuu is going to fix it for the performance core. You will have to use either Balanced or Accuracy core. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Section Dinothawr \end_layout \begin_layout Standard Dinothawr is an indie game made by one of RetroArch's lead authors. It is a simple block puzzler that is similar in gameplay to Sokoban and Kickle Kubicle. It is the first game that is designed from the ground up as a core for RetroArch. The standalone version of this game has a cutdown version of RetroArch included as an integral part of the app. \end_layout \begin_layout Subsection How to run \end_layout \begin_layout Enumerate Go to this website - \begin_inset Flex URL status open \begin_layout Plain Layout https://github.com/libretro/Dinothawr \end_layout \end_inset and select 'Download to ZIP'. \end_layout \begin_layout Enumerate Extract the ZIP file on your device. \end_layout \begin_layout Enumerate Start up RetroArch. Select 'Load Content' (either 'Load Content (Detect Core)' or plain 'Load Content' will do). \end_layout \begin_layout Enumerate Go to the directory where you extracted the contents of the ZIP file to (see step 2). \end_layout \begin_layout Enumerate Select 'dinothawr.game'. The game should now start up. \end_layout \begin_layout Subsection Controls \end_layout \begin_layout Subsubsection RetroPad default mapping \end_layout \begin_layout Standard These are the default button mappings on the RetroPad. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{B BUTTON} \end_layout \end_inset - Push block \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{A BUTTON} \end_layout \end_inset - Go back to previous menu \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{D-PAD} \end_layout \end_inset - Movement \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Section MAME 2003 \end_layout \begin_layout Standard This is a multi-system arcade emulator based on a late 2003 version of MAME (to be specific, it's version 0.78). This old ancient version has been picked because MAME has gotten drastically slower over the years, and a version dating back to 2003 would still be fast enough for running most games on previous-generation videogame consoles and mobile. \end_layout \begin_layout Subsection Libretro port-specific additions \end_layout \begin_layout Subsubsection Midway DCS speed hacks re-addition \end_layout \begin_layout Standard After version 0.72, MAMEdev removed various speedhacks for games using Midway DCS which led to these games being rendered more or less unplayable on current-day hardware (by 2003 standards) back then. These speedhacks have been re-integrated into the MAME 0.78 codebase, and they are of great benefit to the runtime performance of games like Mortal Kombat 1/2/3/Ultimate, NBA Jam and other Midway games using this hardware. \end_layout \begin_layout Subsection Notes \end_layout \begin_layout Itemize You can bring up MAME's OSD GUI by pressing the R2 button on the RetroPad. \end_layout \begin_layout Itemize MAME 2014 supports the RetroKeyboard as an input device as well. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Section MAME 2010 \end_layout \begin_layout Standard This is a multi-system arcade emulator based on a late 2010 version of MAME (to be specific, it's version 0.139). This makes it competitive with MAME4Droid Reloaded which also targets this codebase. This halfway house between MAME 2003 and MAME 2014 is mainly intended for more powerful mobile platforms that were released during 2012 to 2013. While far slower than MAME 2003, it is still measurably faster than MAME 2014. \end_layout \begin_layout Standard Compared to MAME 2003, MAME 2010 has a lot more content available. For instance, Namco System 11/12 games can be played with full sound, Capcom CPS3 support was added, Killer Instinct 1/2 are fully playable, Dynamic recompilation support for 64bit got added, and more. \end_layout \begin_layout Subsection Libretro port-specific additions \end_layout \begin_layout Subsubsection Cave SH3 re-addition \end_layout \begin_layout Standard The Cave SH3 drivers were removed at a specific point in time due to a legal dispute between Cave and MAMEdev. This driver has been readded to MAME 2010. \end_layout \begin_layout Subsection Notes \end_layout \begin_layout Itemize You can bring up MAME's OSD GUI by pressing the R2 button on the RetroPad. \end_layout \begin_layout Itemize MAME 2014 supports the RetroKeyboard as an input device as well. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Section MAME 2014 \end_layout \begin_layout Standard This is a multi-system arcade emulator based on the latest version of MAME (as of this moment, 0.151). Far slower than MAME 2003 and measurably slower than MAME 2010, it makes up for this with increased game compatibility and feature completeness. \end_layout \begin_layout Subsection Libretro port-specific additions \end_layout \begin_layout Subsubsection Cave SH3 re-addition \end_layout \begin_layout Standard The Cave SH3 drivers were removed at a specific point in time due to a legal dispute between Cave and MAMEdev. This driver has been readded to MAME 2014. It will probably be readded soon to MAME mainline as well. \end_layout \begin_layout Subsection Notes \end_layout \begin_layout Itemize You can bring up MAME's OSD GUI by pressing the R2 button on the RetroPad. \end_layout \begin_layout Itemize MAME 2014 supports the RetroKeyboard as an input device as well. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Section Mupen64 Plus \end_layout \begin_layout Standard This is a Nintendo 64 emulator based on the open-source emulator Mupen64 Plus. It is a current work-in-progress that aims primarily at the PC and mobile platforms, such as Android, iOS, Blackberry, and others. It ships with three graphics plugins - of which Glide64 has been worked on the most and is the most accurate, but also the slowest. Development on the other two plugins will take more work. \end_layout \begin_layout Subsection How to run \end_layout \begin_layout Standard Mupen64 Plus does not work on its own, but runs N64 ROM images. These image files need to have one of the following extensions: \end_layout \begin_layout Itemize n64 \end_layout \begin_layout Itemize v64 \end_layout \begin_layout Itemize z64 \end_layout \begin_layout Standard Select one of these. If the image is verified to be OK, it will start up the game. \end_layout \begin_layout Subsection Controls \end_layout \begin_layout Subsubsection RetroPad default mapping \end_layout \begin_layout Standard These are the default button mappings on the RetroPad. It is assumed that your RetroPad has two analog sticks so that the N64's analog stick and the C buttons can be mapped to them. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{B BUTTON} \end_layout \end_inset - (Normal press) N64 B button / (Press and hold with R2) C Button Down \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{A BUTTON} \end_layout \end_inset - (Normal press) N64 A button / (Press and hold with R2) C Button Right \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Y BUTTON} \end_layout \end_inset - (Press and hold with R2) C Button Left \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{X BUTTON} \end_layout \end_inset - (Press and hold with R2) C Button Up \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{L BUTTON} \end_layout \end_inset - N64 L Trigger \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{R BUTTON} \end_layout \end_inset - N64 R Trigger \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{L2 BUTTON} \end_layout \end_inset - N64 Z Trigger \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{R2 BUTTON} \end_layout \end_inset - (Modifier button) - press and hold this plus one of the face buttons to do C button presses \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{D-PAD} \end_layout \end_inset - N64 D-Pad \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{SELECT} \end_layout \end_inset - Toggle between per-game control layouts \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{START} \end_layout \end_inset - N64 Start button \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{LEFT STICK} \end_layout \end_inset - N64 Analog stick \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{RIGHT STICK} \end_layout \end_inset - N64 C buttons mapped to stick like the Gamecube's C Stick \end_layout \begin_layout Subsection Libretro port-specific additions \end_layout \begin_layout Subsubsection Plug-and-play configuration of games \end_layout \begin_layout Standard N64 emulators are traditionally dependent on numerous config/database files that the user has to manually update from time to time. These database files contain core-specific settings needed to play the game correctly (or at all). This varies from Save Type to which Glide 64 settings should be enabled to get the game to look correctly. \end_layout \begin_layout Standard This libretro port tries to automate as much of that stuff as possible and integrate it into the core. No longer will you need to have a Mupen64plus.ini and an RDB database from which all this information will get pulled. \end_layout \begin_layout Standard The Glide64 config file which was previously a necessity has also been totally integrated into the core - to the extent that even the microcode mappings for each game are included. So that config file is not needed any longer either. \end_layout \begin_layout Standard Baking in the config files for glN64 and Rice will take some more time. These have not been included as of yet. \end_layout \begin_layout Subsubsection 60fps framerates in nearly all games with specific core settings \end_layout \begin_layout Standard There have been other N64 emulator forks that have advertised being able to run games like GoldenEye 007 at 60fps. Our approach is most like Project64's in which VI Rate gets increased from the default (1500) to 2200. \end_layout \begin_layout Standard Some games are framerate throttled so they can't ever reach 60fps - however, even these games will benefit from setting VI Refresh to 2200 and Framerate to 'fullspeed'. You will notice that a lot of input latency and slowdown will be removed under these settings. \end_layout \begin_layout Subsubsection Targets OpenGL - both desktop and GLES \end_layout \begin_layout Standard We are using the GLES2 branches of Glide64, Rice and glN64. The libretro port of Mupen64plus targets OpenGL instead of spreading itself thin between Direct3D and OpenGL. We try to make sure that the code works for both desktop GL and GLES at the same time. \end_layout \begin_layout Standard We have also made a lot of optimizations/changes to these rasterizer codebases so that they perform better on our target platforms. We are not anyway near done with that though. \end_layout \begin_layout Subsubsection Accuracy settings \end_layout \begin_layout Standard Turning on all the knobs in a demanding graphics plugin like Glide64 can lead to almost glitchless graphics, but it comes at a heavy performance cost. For this reason, 'accuracy' settings per graphics plugins are introduced as core options. If you care more about double the framerate instead of the current framebuffer image being displayed on a wall billboard in Mario Kart 64, then you can set the Accuracy slider to a less high setting, and vice versa. \end_layout \begin_layout Subsubsection Incorporates low-level RSP next to High-Level RSP - cxd4 \end_layout \begin_layout Standard Certain games will have certain sound effects missing with the default high-leve l RSP plugin, such as GoldenEye 007. Others will simply sound wrong, such as PilotWings 64. The low-level RSP accurately emulates these effects at a signficant performance cost. \end_layout \begin_layout Standard The plugin also handles certain graphics functions that the high-level RSP is missing. For instance, Resident Evil 2 requires that you use the low-level RSP plugin in order for all the FMV movies and backgrounds to work. \end_layout \begin_layout Subsubsection Preconfigured 'sane' controls for various targeted games \end_layout \begin_layout Standard The N64 controller was not always the best pad for certain games, and having to map them to the RetroPad clearly makes that very apparent. We have remapped the controls in various games so that you can get a more pleasant gameplay experience. If you don't like this 'sanitized' control scheme, you can switch on-the-fly between it and the default control scheme by pressing Select (a button which was absent on the N64 pad - which is convenient for us since it gives us an extra button on our RetroPad to do 'stuff' with). \end_layout \begin_layout Standard A couple of examples - Killer Instinct Gold is now mapped like the SNES Killer Instinct, Wipeout 64 is mapped like the PS1 Wipeout 2097, Mortal Kombat Trilogy is mapped like Mortal Kombat on the SNES and PS1, Resident Evil 2 is mapped like the PS1 version, and so on. Since the RetroPad is a replica of the Dual Shock, remapping controls this way just makes a lot more sense. And if you don't want it, you can disable it anyway and/or remap to your heart's content. \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Subsection Known resolvable issues \end_layout \begin_layout Subsubsection Conker BFD and Perfect Dark crash with the low-level RSP plugin \end_layout \begin_layout Standard Don't use the low-level RSP plugin with these games. Instead, use the high-level RSP plugin. \end_layout \begin_layout Subsubsection Resident Evil 2 doesn't work correctly with the high-level RSP plugin \end_layout \begin_layout Standard You need to use the low-level RSP plugin for this game to work correctly. \end_layout \begin_layout Subsubsection I can't use the Rice plugin \end_layout \begin_layout Standard Make sure that a config file called RiceVideoLinux.ini has been placed in your 'system' directory. The libretro Mupen64plus core still depends on this file being there in order to execute the Rice plugin. \end_layout \begin_layout Subsection Known issues \end_layout \begin_layout Standard Consider the Mupen64 core right now at an advanced alpha state. Lots of issues are known about and will be looked at. The most prominent ones we are aware of are listed below. \end_layout \begin_layout Subsubsection iOS dynamic recompiler bugs \end_layout \begin_layout Standard Right now the dynamic recompiler for iOS is not at parity with Android. This means that certain games might either crash or freeze at certain points due to bugs still lurking in the code. One example of this is GoldenEye 007 crashing at startup. We are working hard on resolving these remaining issues so that the iOS port is at least equal to the Android port. \end_layout \begin_layout Subsubsection Wobbling textures with Glide64 in certain games \end_layout \begin_layout Standard Ground texture wobbling seems to occur in games like Super Mario 64, Star Fox 64, F-Zero X and other games depending on how close the camera is to the ground. This seems to be an issue with Glide64 in general. We will try to investigate this issue. \end_layout \begin_layout Subsubsection GoldenEye 007 - Glide64 - frigate level - water surface disappearing vertices \end_layout \begin_layout Standard You will be able to notice significant polygon breakup when first entering this stage on the boat. Vertices of the water surface appear black depending on the proximity of the camera to the surface. This, like 3.3.2, seems to be also an issue with Glide64 that we will have to investigate. \end_layout \begin_layout Subsubsection Broken framebuffer effects in glN64 \end_layout \begin_layout Standard This is a known issue and it will probably be trivial to hook this up. \end_layout \begin_layout Subsubsection Other glN64/Rice issues \end_layout \begin_layout Standard Most of the hard work has gone into Glide64 at this point so the glN64/Rice side has not been actively worked on - though we intend to do so eventually. \end_layout \begin_layout Subsubsection Tsumi to Batsu (Sin and Punishment) crashes either at startup or at exit \end_layout \begin_layout Standard Known issue and currently no fix for it. Will have to be debugged. \end_layout \begin_layout Subsubsection Star Wars: Shadows of the Empire sometimes boots, sometimes crashes \end_layout \begin_layout Standard This is a known issue, and there is currently no fix for it. \end_layout \begin_layout Subsubsection Pokemon Puzzle League doesn't work \end_layout \begin_layout Standard This is a known issueand there is currently no fix for it. \end_layout \begin_layout Subsubsection Blast Corps - Crashes after Rare logo with dynarec on ARM devices \end_layout \begin_layout Standard This is a known issue. The very same issue happens with Mupen64 Plus AE too. Currently, the only way to play this game on an ARM device would be to switch the CPU core to 'Cached interpreter'. This will however make the game run way too slow (possible exception being Apple A7 CPUs and competing hardware). \end_layout \begin_layout Subsubsection Perfect Dark is very slow in scenes with framebuffer effects or motion blur \end_layout \begin_layout Standard This is a known issue. The issue is that the only way to accelerate these scenes would be to use Hardware Framebuffer Emulation, and that has drawbacks of its own such as vertices with black textures after certain scenes have ran (such as the Spycam). For now there is no good fix for this other than doing it all on the CPU, which is CPU-intensive and slow. \end_layout \begin_layout Subsubsection Conker's BFD - Conker has no shadow \end_layout \begin_layout Standard This is a known issue. Shadows depend on a depth texture being rendered, and the only way to render these is to use Hardware Framebuffer Emulation. While we can enable this mode, it has severe drawbacks in other areas right now that precludes its use. Therefore, currently the shadow is stubbed out. \end_layout \begin_layout Subsubsection PilotWings 64 - There is a very annoying long black vertice obscuring a great part of the screen \end_layout \begin_layout Standard This is a known issue, and it seems to happen with glN64 too and mainline Mupen64 in general. What is supposed to happen there is that a shadow on the ground should be in place of these broken vertice spans. A fix is not yet known. There is a 'duct-tape hack' core setting that makes this 'glitch' somewhat more bearable - it makes the culled vertice appear translucent instead of solid - which means you can watch through it. \end_layout \begin_layout Subsubsection Legend of Zelda: Majora's Mask - subscreen framebuffer image takes about five seconds to appear \end_layout \begin_layout Standard This is a known issue, and a fix is not yet known. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Section NX Engine \end_layout \begin_layout Standard This is a game engine capable of running the game \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Cave Story} \end_layout \end_inset (Japanese title: \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Doukutsu Monogatari} \end_layout \end_inset ). It is based on an open-source game engine recreation called NX Engine. An extensive code rewrite has been done for the purposes of increased portabili ty and performance. \end_layout \begin_layout Subsection How to run \end_layout \begin_layout Standard In order to run the game, you need to have the original datafiles from the original freeware PC version. \end_layout \begin_layout Enumerate Go to this website - \begin_inset Flex URL status open \begin_layout Plain Layout https://github.com/libretro/nxengine-libretro \end_layout \end_inset and select 'Download to ZIP'. \end_layout \begin_layout Enumerate Extract the ZIP file on your device. \end_layout \begin_layout Enumerate Start up RetroArch. Select 'Load Content' (either 'Load Content (Detect Core)' or plain 'Load Content' will do). \end_layout \begin_layout Enumerate Go to the directory where you extracted the contents of the ZIP file to (see step 2). Select the directory 'datafiles'. \end_layout \begin_layout Enumerate Select 'Doukutsu.exe'. The game should now start up. \end_layout \begin_layout Subsection Controls \end_layout \begin_layout Subsubsection RetroPad default mapping \end_layout \begin_layout Standard These are the default button mappings on the RetroPad. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{B BUTTON} \end_layout \end_inset - Jump \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Y BUTTON} \end_layout \end_inset - Shoot \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{X BUTTON} \end_layout \end_inset - Map screen \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{L BUTTON} \end_layout \end_inset - Weapon cycle left \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{R BUTTON} \end_layout \end_inset - Weapon cycle right \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{D-PAD} \end_layout \end_inset - Movement \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{SELECT} \end_layout \end_inset - Options screen \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{START} \end_layout \end_inset - Inventory screen \end_layout \begin_layout Subsection Libretro port-specific additions \end_layout \begin_layout Subsubsection Caches all assets - avoids disk I/O overhead \end_layout \begin_layout Standard The original NXEngine source was quite inefficiently written and had very high disk I/O overhead. This all but killed performance on the game consoles where disk I/O is very slow. What happens instead now is that instead of dumping all content from the main binary to disk, it caches it in memory so that there is zero overhead from accessing assets. This way, NXEngine is playable at fullspeed on any system without any disk I/O spikes - including consoles. \end_layout \begin_layout Subsubsection Ability to switch between 50fps (default) and 60fps \end_layout \begin_layout Standard The original game ran at 50 frames per second. For the libretro port, we have made an optional toggle so you can switch the game to 60 frames per second. You can do this by pressing the Select button to go to the Options screen, and changing 'FPS' from 50 to 60, and vice versa. \end_layout \begin_layout Section PCSX ReARMed \end_layout \begin_layout Standard This is a Sony PlayStation 1 emulator based on the open-source emulator PCSX Reloaded. It has been specifically optimized for mobile platforms, such as Android, iOS and Pandora. It also has a software-rendered graphics renderer, called NEON GPU plugin, that is more accurate than most PlayStation 1 emulators. \end_layout \begin_layout Subsection How to run \end_layout \begin_layout Standard PCSX ReARMed does not work on its own, but runs PlayStation1 CD images. These image files need to have one of the following extensions: \end_layout \begin_layout Itemize bin \end_layout \begin_layout Itemize cue \end_layout \begin_layout Itemize img \end_layout \begin_layout Itemize mdf \end_layout \begin_layout Itemize pbp \end_layout \begin_layout Itemize toc \end_layout \begin_layout Itemize cbn \end_layout \begin_layout Itemize m3u \end_layout \begin_layout Standard Select one of these. If the image is verified to be OK,it will start up the game. \end_layout \begin_layout Subsection Controls \end_layout \begin_layout Subsubsection RetroPad default mapping \end_layout \begin_layout Standard These are the default button mappings on the RetroPad. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{B BUTTON} \end_layout \end_inset - PS1 X button \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{A BUTTON} \end_layout \end_inset - PS1 Circle button \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Y BUTTON} \end_layout \end_inset - PS1 Square button \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{X BUTTON} \end_layout \end_inset - PS1 Triangle button \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{L BUTTON} \end_layout \end_inset - PS1 L1 Button \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{R BUTTON} \end_layout \end_inset - PS1 R1 Button \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{L2 BUTTON} \end_layout \end_inset - PS1 L2 Button \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{R2 BUTTON} \end_layout \end_inset - PS1 R2 Button \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{D-PAD} \end_layout \end_inset - PS1 D-Pad \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{SELECT} \end_layout \end_inset - PS1 Select button \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{START} \end_layout \end_inset - PS1 Start button \end_layout \begin_layout Subsubsection RetroPad DualShock controls \end_layout \begin_layout Standard To enable this mode, you need to go to Core Options and set 'Pad 1 Type' to 'analog'. Your RetroPad is assumed to have two analog sticks to be able to use this mode. Note that not all games might work in DualShock mode, and vice versa - so switch between them if the controls don't work. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{LEFT STICK} \end_layout \end_inset - PS1 Left Analog Stick \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{RIGHT STICK} \end_layout \end_inset - PS1 Right Analog Stick \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{L3} \end_layout \end_inset - PS1 L3 Button \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{R3} \end_layout \end_inset - PS1 R3 Button \end_layout \begin_layout Subsection Setting up BIOS files \end_layout \begin_layout Standard The compatibility of PCSX ReARMed is increased a lot by using real BIOS firmware images. \end_layout \begin_layout Standard PCSX ReARMed looks for the following BIOS files: \end_layout \begin_layout Itemize scph1001.bin \end_layout \begin_layout Itemize scph5501.bin \end_layout \begin_layout Itemize scph7001.bin \end_layout \begin_layout Standard These files should be placed inside your System directory. If your system directory path does not point to anything, it will try to load the BIOS files from the same directory as the CD image. \end_layout \begin_layout Subsection Core options \end_layout \begin_layout Subsubsection Increasing graphics resolution \end_layout \begin_layout Standard You can increase the internal graphics resolution by enabling the core option 'Enable NEON enhanced resolution (slow)' This will force the core to render at a resolution of 1024x512 \begin_inset Foot status collapsed \begin_layout Plain Layout This mode is deactivated on games that have high-resolution interlaced graphics modes, such as Tekken 3 and Tobal 2. Setting this option to 'ON' or 'OFF' will make no change. \end_layout \end_inset . This will significantly increase the quality of the graphics, but it will also impact performance. Only enable this option if you are on a fast platform with enough CPU power - otherwise you're best off leaving this core option 'off'. \end_layout \begin_layout Subsubsection Disabling interlacing for better performance with interlaced games \end_layout \begin_layout Standard High-resolution interlaced games such as Tekken 3 and Tobal 2 would typically be displayed in interlaced mode on a real PlayStation. The emulator typically renders these games with interlacing turned off. This however will have an impact on performance. If you find that your platform for whatever reason is falling below fullspeed, it can help to set the core option 'Interlacing' to 'ON'. \end_layout \begin_layout Subsubsection Disabling dynarec for platforms that don't support JIT compilation (Windows Phone/RT, non-jailbroken iOS) \end_layout \begin_layout Standard Normally, PCSX ReARMed starts up with the dynarec CPU core being automatically activated. \end_layout \begin_layout Standard There are some platforms that don't allow for JIT compilation inside an app (which is what the dynarec CPU core relies upon). These include: \end_layout \begin_layout Itemize Non-jailbroken iOS \end_layout \begin_layout Itemize Windows RT \end_layout \begin_layout Itemize Windows Phone \end_layout \begin_layout Standard You will need to disable the core option 'Dynarec' if you want to be able to run this core on such a device. Be aware that disabling the dynarec is very CPU-intensive and might result in PCSX ReARMed not being able to run fullspeed on yur device. Disable dynarec therefore only if you absolutely must. \end_layout \begin_layout Subsection Known outstanding issues \end_layout \begin_layout Subsubsection Garbled sound samples at times \end_layout \begin_layout Standard Sound emulation is not perfect. At some point we intend to backport the latest sound driver from PCSX Reloaded and offer a way to toggle between the original driver and the latest PCSXR one. The original PCSX ReARMed version was geared around the Pandora, which is limited by a 1Ghz Cortex A8 CPU - concessions had to be made. Today's mobile devices are far more powerful than this and should be capable of much more demanding sound emulation. \end_layout \begin_layout Subsubsection Broken geometry in Jumping Flash 1/2 \end_layout \begin_layout Standard This is caused by an inaccurate Geometry Transfer Engine plugin used in PCSX ReARMed. A core option will probably have to be included at some point that allows the user to switch between inaccurate/fast GTE and accurate GTE emulation. \end_layout \begin_layout Subsubsection Random game does not work \end_layout \begin_layout Standard First of all, check that you are running with a real BIOS image. You can tell if this is the case if PCSX ReARMed does not display a warning at startup telling you that it could not find a BIOS file. The internal HLE BIOS emulation is very incomplete and might cause many games to be buggy. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Section TyrQuake \end_layout \begin_layout Standard This is a Quake 1 game engine based on the open-source Quake 1 game engine TyrQuake. Unlike other Quake 1-based game engines, it focuses on accuracy to the original DOS game and portability. As such, it features no graphical enhancements and the renderer is software-bas ed. \end_layout \begin_layout Subsection How to run \end_layout \begin_layout Standard TyrQuake does not work on its own, but runs Quake 1 PAK data archives. \end_layout \begin_layout Standard Select either pak0.pak or pak1.pak from the shareware version or the registered version. If the files are OK, it will start up the game. \end_layout \begin_layout Subsection How to run mission packs \end_layout \begin_layout Standard It is also possible to run mission packs with TyrQuake. \end_layout \begin_layout Standard Place the necessary files in subdirs hipnotic/ and rogue/. Make sure the original Quake 1 datafiles are in the root directory. \end_layout \begin_layout Standard Start pak0.pak from the hipnotic/rogue directory. Instead of launching the original game, it should now start the mission pack. \end_layout \begin_layout Subsection Controls \end_layout \begin_layout Subsubsection RetroPad default mapping \end_layout \begin_layout Standard These are the default button mappings on the RetroPad. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Y BUTTON} \end_layout \end_inset - Shoot \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{B BUTTON} \end_layout \end_inset - Jump \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{A BUTTON} \end_layout \end_inset - Weapon cycle \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{X BUTTON} \end_layout \end_inset - (Press and hold) free look \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{L BUTTON} \end_layout \end_inset - Strafe left \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{R BUTTON} \end_layout \end_inset - Strafe right \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{D-PAD} \end_layout \end_inset - Movement \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{START} \end_layout \end_inset - Bring up Options Menu \end_layout \begin_layout Subsubsection RetroPad Dual analog controls \end_layout \begin_layout Standard To enable this mode, you need to go to Core Options and set Gamepad type to 'dual-analog'. Your RetroPad is assumed to have two analog sticks to be able to use this mode. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{LEFT STICK} \end_layout \end_inset - X minus and positive X strafes left and right, Y minus and positive Y moves forward and backwards \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{RIGHT STICK} \end_layout \end_inset - Free look \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{R3} \end_layout \end_inset - Center view \end_layout \begin_layout Subsection Libretro port-specific additions \end_layout \begin_layout Subsubsection Enabling/disabling software bilinear interpolation \end_layout \begin_layout Standard The original Quake software renderer had no filtering routines to speak of for textures. Textures would appear pixelated if you came close to them. Enabling this (from the Quake settings menu) will apply the kernel filtering algorithm from Unreal 1's software renderer on each texture. This might look more aesthetically pleasing to people who prefer quasi-3D hardware bilinear filtered textures to nearest textures. Enabling this might come at a negligible performance cost. \end_layout \begin_layout Subsubsection Enabling/disabling mipmapping \end_layout \begin_layout Standard Normally, Quake's software renderer has this always enabled. Objects in the distance will use lower-quality texture assets than the ones closer to the player. Disabling this (from the Quake settings menu) will render each object with the most high-quality texture available, no matter what the distance is to the player. Enabling this will come at a big performance cost - so only enable it if your platform is powerful enough. \end_layout \begin_layout Subsubsection Enabling/disabling animation interpolation \end_layout \begin_layout Standard By default the game updates animations of its 3D models at a very sluggish rate - 11 frames per second approximately. Enabling this option (from the Quake settings menu) allows you to enable frame interpolation so that the movements of monsters will appear much smoother. Enabling this might come at a negligible performance cost. \end_layout \begin_layout Subsubsection Enabling/disabling third person view \end_layout \begin_layout Standard By default, Quake is played from a first person perspective. Enabling this option (from the Quake settings menu) allows you to play Quake from a third person perspective. There are two camera modes to choose from - 'Clamped' and 'Clipped'. 'Clamped' will not allow the camera to pass through walls and it will try to prevent showing you any of the empty 'clip space' that exists beyond the game world. When this 'clamping' happens, the camera will zoom in to your player. Setting it to 'Clipped' does not bound the camera to the game world and does not zoom in on the player - instead, it will simply show the empty clip space that exists beyond the game world. It is up to user preference which of the two he/she prefers. \end_layout \begin_layout Subsubsection Setting framerate to 50 or 60fps \end_layout \begin_layout Standard The original Quake never ran at a fixed framerate, and it took quite a few years for PCs to even reach the state where they were able to run Quake at 50 or 60fps. Libretro TyrQuake assumes that you will want to run Quake at either a constant 50 or 60 frames per second. You can set the framerate to either 50fps or 60fps from the Quake settings menu. \end_layout \begin_layout Subsection Core options \end_layout \begin_layout Subsubsection Increasing graphics resolution \end_layout \begin_layout Standard Because Quake is using software rendered graphics and because the original sourcecode to Quake 1 had hand-tuned assembly routines for 486/early Pentium 1 CPUs (routines which can't be used on today's PCs), it might come as a surprise that TyrQuake still demands high system requirements in order to run it above the default resolution (320x200). \end_layout \begin_layout Standard By increasing the internal resolution with the core option 'Internal resolution' , the graphical quality of the game can be significantly enhanced at the expense of speed. After each internal resolution change, you will need to restart the TyrQuake core in order for the changes to be applied. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \end_body \end_document ================================================ FILE: archive/retroarch-manual.lyx ================================================ #LyX 2.0 created this file. For more info see http://www.lyx.org/ \lyxformat 413 \begin_document \begin_header \textclass article \use_default_options true \maintain_unincluded_children false \language english \language_package default \inputencoding auto \fontencoding global \font_roman default \font_sans default \font_typewriter default \font_default_family default \use_non_tex_fonts false \font_sc false \font_osf false \font_sf_scale 100 \font_tt_scale 100 \graphics default \default_output_format default \output_sync 0 \bibtex_command default \index_command default \paperfontsize default \spacing single \use_hyperref true \pdf_title "RetroArch Android Manual" \pdf_author "Hans-Kristian Antzen, Daniel De Matteis" \pdf_bookmarks true \pdf_bookmarksnumbered false \pdf_bookmarksopen false \pdf_bookmarksopenlevel 1 \pdf_breaklinks false \pdf_pdfborder false \pdf_colorlinks true \pdf_backref false \pdf_pdfusetitle true \papersize default \use_geometry false \use_amsmath 1 \use_esint 1 \use_mhchem 1 \use_mathdots 1 \cite_engine basic \use_bibtopic false \use_indices false \paperorientation portrait \suppress_date false \use_refstyle 1 \index Index \shortcut idx \color #008000 \end_index \secnumdepth 5 \tocdepth 5 \paragraph_separation indent \paragraph_indentation default \quotes_language english \papercolumns 1 \papersides 1 \paperpagestyle default \tracking_changes false \output_changes false \html_math_output 0 \html_css_as_file 0 \html_be_strict false \end_header \begin_body \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename retroarch-android/logo.png lyxscale 50 scale 50 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Title RetroArch Android (v0.9.8) \end_layout \begin_layout Author Hans Kristian Arntzen, Daniel De Matteis, Michael Lelli \end_layout \begin_layout Standard \begin_inset CommandInset toc LatexCommand tableofcontents \end_inset \end_layout \begin_layout Section Introduction \end_layout \begin_layout Standard RetroArch Android is an app that has been designed to run and play: \end_layout \begin_layout Itemize Games \end_layout \begin_layout Itemize Emulators \end_layout \begin_layout Standard Emulators and games that can be run on RetroArch come in the form of pluggable 'engines' which are called 'libretro ports'. The version that you just installed already has most of the full library of 'cores' preinstalled. \end_layout \begin_layout Section Disclaimer \end_layout \begin_layout Standard RetroArch Android is released for free and will always be free. There are no ads (push or otherwise), there is no 'spying' going on in the form of analytics or collecting stats, there is no 'paid DLC', and on and on - all the unsavory and bad aspects of this 'new generation of computing' are not to be found here. It will never be sold with a pricetag - not even disguised as a 'donationware version'. If you happen to have 'paid' for RetroArch Android or a derivative of it, you have been scammed and you should probably demand your money back from the scam artist in question (and scam artists they are). \end_layout \begin_layout Standard Just because the GPL allows people to make derivative copies of RetroArch for commercial purposes does not mean that we support it or even approve of it. If you sell RetroArch or a derivative copy of it for any commercial purpose, you are part of the problem and you need to be learnt a quick lesson in etiquette. Note to any 'entrepreneurs' out there that might be tempted by this 'easy route to makin' some money' - I honestly wouldn't bother - we will undercut you by offering this all for free and doing a better job at it to boot. That and I severely doubt you can come up with many trinkets that will persuade people to throw away their money on a derivative version when they can have it all for free to begin with - just saying - save yourself the time and the effort, because it isn't going to work out. \end_layout \begin_layout Section How to run \end_layout \begin_layout Subsection Select a core \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename retroarch-android/maE85W6.png lyxscale 50 scale 30 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash caption{Select a core from this menu.} \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename retroarch-android/UhU7QrR.png lyxscale 50 scale 30 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash caption{After selecting the core, you will need to load a game.} \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Standard A 'libretro core' supports games with certain extensions. Below you will find the list of cores that came preinstalled with this app and what file extensions they support. \end_layout \begin_layout Itemize SNES9x Next \begin_inset Newline newline \end_inset Used for: playing SNES games (Super Nintendo Entertainment System) \begin_inset Newline newline \end_inset Author(s): SNES9x team, OV2, Bearoso, zones, Squarepusher (fork) \begin_inset Newline newline \end_inset Recommended system requirements: ARM Cortex A9 multi-core device (and up) \begin_inset Newline newline \end_inset Extensions: "smc|fig|sfc|gd3|gd7|dx2|bsx|swc|zip|SMC|FIG| \begin_inset Newline newline \end_inset SFC|BSX|GD3|GD7|DX2|SWC|ZIP" \end_layout \begin_layout Itemize VBA Next \begin_inset Newline newline \end_inset Used for: playing Game Boy Advance games \begin_inset Newline newline \end_inset Recommended system requirements: ARM Cortex A9 multi-core based device (and up) \begin_inset Newline newline \end_inset Author(s): Forgotten, VBA-M team, Squarepusher (fork) \begin_inset Newline newline \end_inset Extensions: "gba|GBA|zip|ZIP" \end_layout \begin_layout Itemize FCEUmm \begin_inset Newline newline \end_inset Used for: playing NES games (Nintendo Entertainment System) \begin_inset Newline newline \end_inset Author(s): CaH4e3, original FCEU authors \begin_inset Newline newline \end_inset Extensions: "fds|FDS|zip|ZIP|nes|NES|unif|UNIF" \end_layout \begin_layout Itemize NEStopia \begin_inset Newline newline \end_inset Used for: playing NES games (Nintendo Entertainment System) \begin_inset Newline newline \end_inset Author(s): Marty \begin_inset Newline newline \end_inset Extensions supported: "nes|NES|zip|ZIP|fds|FDS" \end_layout \begin_layout Itemize Gambatte \begin_inset Newline newline \end_inset Used for: playing GameBoy / GameBoy Color games \begin_inset Newline newline \end_inset Author(s): Sinamas \begin_inset Newline newline \end_inset Extensions supported: "gb|gbc|dmg|zip|GB|GBC|DMG|ZIP" \end_layout \begin_layout Itemize Final Burn Alpha \begin_inset Newline newline \end_inset Used for: playing arcade games \begin_inset Newline newline \end_inset Author(s): Dave, FBA Team (Barry Harris & co) \begin_inset Newline newline \end_inset Extensions supported: \begin_inset Quotes eld \end_inset zip|ZIP \begin_inset Quotes erd \end_inset \end_layout \begin_layout Itemize Genesis Plus GX \begin_inset Newline newline \end_inset Used for: playing Sega Genesis / Master System / Game Gear / Sega CD games \begin_inset Newline newline \end_inset Author(s): Charles McDonald, ekeeke \begin_inset Newline newline \end_inset Extensions supported: "md|smd|bin|cue|gen|zip|MD|SMD|bin|iso| \begin_inset Newline newline \end_inset ISO|CUE|GEN|ZIP|sms|SMS|gg|GG|sg|SG" \end_layout \begin_layout Itemize NX Engine \begin_inset Newline newline \end_inset Used for: playing Cave Story / Doukutsu Monogatari \begin_inset Newline newline \end_inset Author(s): Caitlin Shaw (rogueeve) \begin_inset Newline newline \end_inset Extensions supported: \begin_inset Quotes eld \end_inset exe|EXE|zip|ZIP \begin_inset Quotes erd \end_inset \end_layout \begin_layout Itemize PCSX ReARMed \begin_inset Newline newline \end_inset Used for: playing PlayStation1 games \begin_inset Newline newline \end_inset Author(s): PCSX Team, Notaz, Exophase (GPU plugin) \begin_inset Newline newline \end_inset Extensions supported: "bin|cue|img|mdf|pbp|cbn" \end_layout \begin_layout Itemize Prboom \begin_inset Newline newline \end_inset Used for: playing Doom, Doom 2, Ultimate Doom, Final Doom, and mods \begin_inset Newline newline \end_inset Author(s): Various \begin_inset Newline newline \end_inset Extensions supported: "WAD|wad|IWAD|iwad" \end_layout \begin_layout Itemize Mednafen NGP \begin_inset Newline newline \end_inset Used for: playing Neo Geo Pocket Color games \begin_inset Newline newline \end_inset Author(s): Original Neopop authors, Ryphecha \begin_inset Newline newline \end_inset Extensions supported: "ngp|NGP|ngc|NGC|zip|ZIP" \end_layout \begin_layout Itemize Mednafen WonderSwan \begin_inset Newline newline \end_inset Used for: playing WonderSwan / WonderSwan Color / WonderSwan Crystal games \begin_inset Newline newline \end_inset Author(s): Original Cygne authors, Ryphecha \begin_inset Newline newline \end_inset Extensions supported: "ws|WS|wsc|WSC|zip|ZIP" \end_layout \begin_layout Itemize Mednafen Virtual Boy \begin_inset Newline newline \end_inset Used for: playing Virtual Boy games \begin_inset Newline newline \end_inset Author: Ryphecha \begin_inset Newline newline \end_inset Extensions supported: "vb|VB|vboy|VBOY|bin|BIN|zip|ZIP" \end_layout \begin_layout Itemize Mednafen PC Engine \begin_inset Newline newline \end_inset Used for: playing PC Engine / Supergrafx 16 / PC Engine CD games \begin_inset Newline newline \end_inset Author: Ryphecha \begin_inset Newline newline \end_inset Extensions supported: "pce|PCE|sgx|SGX|cue|CUE|zip|ZIP" \end_layout \begin_layout Standard Select one of these cores in the menu. \end_layout \begin_layout Subsection Select a game \end_layout \begin_layout Standard After you have selected a core, you will need to select a compatible game from the filebrowser. It will then attempt to load the core with that specific game. \end_layout \begin_layout Section Controls \end_layout \begin_layout Subsection Touchscreen overlay \end_layout \begin_layout Standard RetroArch Android uses an overlay as a 'mock' gamepad to play with. The 'overlay' controls will always be bound to Player 1. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename retroarch-android/Rr2Nvgo.png lyxscale 50 scale 50 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash caption{'Gamepad overlay' screen.} \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Subsection Touchscreen menu navigation \end_layout \begin_layout Standard Each touchscreen overlay has a couple of screens that can be navigated to. To go to the next screen of the overlay, you press the 'circle' icon at the bottom. \end_layout \begin_layout Standard Most of the overlays that come bundled with RetroArch Android have the same screen order. \end_layout \begin_layout Subsubsection Gamepad screen \end_layout \begin_layout Standard You can control the game with this screen. Illustrated is a controller called 'RetroPad'. It is laid out like a SNES pad with PlayStation-style shoulder \end_layout \begin_layout Standard buttons. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename retroarch-android/1ZhxUo2.png lyxscale 50 scale 50 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash caption{'Quick Menu' screen.} \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Subsubsection Quick Menu screen \end_layout \begin_layout Standard The actions on this screen have various effects on the game currently running. \end_layout \begin_layout Itemize LOAD STATE - Load a save state from the currently selected save state slot. \end_layout \begin_layout Itemize SAVE STATE - Save state to the currently selected save state slot. \end_layout \begin_layout Itemize STATE MINUS - Go back one save state slot. \end_layout \begin_layout Itemize STATE PLUS - Go forward one state slot. \end_layout \begin_layout Itemize REWIND - Rewind the game in real-time. Note - the 'Rewind' option needs to be enabled at the Settings menu or else this option won't work. \end_layout \begin_layout Itemize SLOWMOTION - Press and hold this button to let the game run in slowmotion. \end_layout \begin_layout Itemize RESET - Resets the game/system. \end_layout \begin_layout Itemize FAST FORWARD - Fast forward the game in real-time. \end_layout \begin_layout Itemize NEXT SHADER - Load the next shader in the folder (NOTE: only if shaders are enabled) \end_layout \begin_layout Itemize PREVIOUS SHADER - Load the previous shader in the folder (NOTE: only if shaders are enabled) \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename retroarch-android/hCwKqVN.png lyxscale 50 scale 50 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash caption{'Gameplay' screen.} \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Subsubsection Gameplay screen \end_layout \begin_layout Standard This screen is useful for when you are playing with an USB or Bluetooth gamepad but you would still like to have access to the Quick Menu or Gamepad screen without outright disabling overlays. If you press the 'icon' at the bottom of this screen, you will go back to the 'Gamepad' screen'. \end_layout \begin_layout Subsection Variations \end_layout \begin_layout Standard RetroArch Android comes packaged with a number of different-looking overlays. You can select from a number of different overlays in the Settings menu. Below is a list of different overlays: \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename retroarch-android/overlays.png lyxscale 50 scale 50 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash caption{All the default overlays packaged with RetroArch Android.} \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Subsubsection Making your own custom overlays \end_layout \begin_layout Standard You can make your own custom overlays for use with RetroArch Android. If you want to learn how to do this, you should read the 'Overlay Guide'. \end_layout \begin_layout Subsection USB gamepads \end_layout \begin_layout Standard Next to the standard touchscreen input, RetroArch Android autodetects and autoconfigures various input devices automatically. Most of these are USB joysticks/gamepads. \end_layout \begin_layout Standard A list of the gamepads that are supported by autodetection can be found inside the app. (go to Help). \end_layout \begin_layout Standard You connect the device to your tablet/phone. You press a button while ingame. If your pad is supported, it should bring up a message saying: \begin_inset Quotes eld \end_inset RetroPad #? detected: \begin_inset Quotes eld \end_inset and then the name of the device it found. Buttons and control layout will then be autoconfigured and mapped to the RetroPad layout. \end_layout \begin_layout Subsubsection Unsupported gamepads \end_layout \begin_layout Standard If your pad is unsupported, it will likely show \begin_inset Quotes eld \end_inset Unknown HID \begin_inset Quotes erd \end_inset instead. If you want this pad supported, contact us. \end_layout \begin_layout Subsubsection Notes \end_layout \begin_layout Standard If a USB gamepad that is listed above does not work immediately, your controller may require a powered USB hub or perhaps a HID driver may be missing of sorts. \end_layout \begin_layout Subsection Bluetooth \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename retroarch-android/sVWyw8c.png lyxscale 50 scale 35 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash caption{Setting an IME app from the RetroArch menu by clicking on the 'Settings' icon.} \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Standard RetroArch supports Bluetooth right now only through the use of IME apps. A couple of IME apps are supported by RetroArch Android - if you use the default key layouts with the IME apps listed below, your pads will be automatic ally configured: \end_layout \begin_layout Itemize \begin_inset Flex URL status collapsed \begin_layout Plain Layout https://play.google.com/store/apps/details?id=com.dancingpixelstudios.sixaxiscontrol ler \end_layout \end_inset Dancing Pixel Studios SixAxis Controller \end_layout \begin_layout Itemize \begin_inset Flex URL status collapsed \begin_layout Plain Layout https://play.google.com/store/apps/details?id=com.ccpcreations.android.WiiUseAndroid \end_layout \end_inset ccpcreations.Wiiuse.Android \end_layout \begin_layout Standard Remember that you will have to change your Input Method to the needed IME first before starting RetroArch. This can also be done from the menu by clicking on the top righthand side 'Settings' icon and then selecting 'Input Method' (see image). \end_layout \begin_layout Subsection Notes \end_layout \begin_layout Standard When using PS3 controller via Bluetooth, use SixAxis adapter app and after you've got the controller setup, make sure to go to menu then preferences and then Game pad settings, and enable Gamepad. This turns it into a native android controller and no IME switch is needed. Same for the MOGA controller via bluetooth, make sure to use the MOGA Universal Driver and not the one that MOGA recommends. In the app, make sure 'Enable left analog input' is checked, and that it's in System Mode to make it a native gamepad for android and no need to switch IMEs. \end_layout \begin_layout Section Settings \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename retroarch-android/Emu9nsQ.png lyxscale 50 scale 35 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash caption{'Settings' menu.} \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Standard You can configure many aspects of RetroArch. To go to the Settings menu, click on the 'Settings' icon at the top righthand side of the screen and then select 'Settings'. \end_layout \begin_layout Subsection Path Settings \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename retroarch-android/4i6EGD7.png lyxscale 50 scale 35 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash caption{'Path Settings' screen.} \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Itemize ROM Directory \begin_inset Newline newline \end_inset Set the directory that will be used as a default starting point for the filebrowser. \end_layout \begin_layout Itemize Save Files - Enable custom directory \begin_inset Newline newline \end_inset Enables use of custom save file folder. (.srm) save files will be saved and loaded to the configured directory. if not enabled, save files will reside in ROM folder. \end_layout \begin_layout Itemize Save Files - Savefile directory \begin_inset Newline newline \end_inset Sets directory where to save and load game save files. \end_layout \begin_layout Itemize Save States - Enable custom directory \begin_inset Newline newline \end_inset Enables use of custom save statefolder. (.state) save states will be saved and loaded to configured directory. If not enabled, save states will reside in ROM folder. \end_layout \begin_layout Itemize Save state directory \begin_inset Newline newline \end_inset Sets directory where to save and load game save states. \end_layout \begin_layout Subsection System Settings \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename retroarch-android/WOfUmx7.png lyxscale 50 scale 35 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash caption{'System Settings' screen.} \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Itemize Auto load state \begin_inset Newline newline \end_inset Loads an automatically created savestate at startup. \end_layout \begin_layout Itemize Auto save state \begin_inset Newline newline \end_inset This will make a save state when you exit the game. This auto savestate will be automatically loaded the next time you start up the \begin_inset Newline newline \end_inset game. Useful for on-the-go gaming. \end_layout \begin_layout Itemize Rewinding Enable \begin_inset Newline newline \end_inset This allows you to rewind the game in real-time to undo 'mistakes' you made while playing the game. (NOTE - this is very CPU intensive - you should only enable this if the core is running at least 2x realtime on your system). \end_layout \begin_layout Subsection Video Settings \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename retroarch-android/3gbr7az.png lyxscale 50 scale 35 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash caption{'Video Settings' screen.} \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Itemize Vsync \begin_inset Newline newline \end_inset Unchecking this will cause screen tearing but faster performance. \end_layout \begin_layout Itemize Sync refreshrate to screen \begin_inset Newline newline \end_inset Synchronize RetroArch's refresh rate to the screen's refresh rate (recommended - some screens have refresh rates below 59.95Hz and need this enabled to get good audio/video sync). \end_layout \begin_layout Itemize Forced refresh rate (Hz) \begin_inset Newline newline \end_inset Force a specific refresh rate to be detected. Only use this if auto-detection of refresh rate reports wrong refresh rate. \end_layout \begin_layout Itemize Auto-rotate \begin_inset Newline newline \end_inset Will auto-rotate the screen for vertically oriented games. \end_layout \begin_layout Itemize Aspect ratio \begin_inset Newline newline \end_inset Select the aspect ratio to enforce. \end_layout \begin_layout Itemize Shaders (1st pass) Bilinear filter \begin_inset Newline newline \end_inset Applies bilinear filtering, smooths out edges (setting still apply even if no shader is selected). \end_layout \begin_layout Itemize Shaders (1st pass) Enable \begin_inset Newline newline \end_inset Enable the currently selected shader. \end_layout \begin_layout Itemize Shaders (1st pass) XML Shader \begin_inset Newline newline \end_inset Select this option to select a shader from the filesystem. RetroArch comes prepackaged with a collection of shaders. \end_layout \begin_layout Itemize Shaders (Multi-pass) Render-to-texture \begin_inset Newline newline \end_inset Render first pass to a texture (FBO). Stretch to screen with second shader. \end_layout \begin_layout Itemize Shaders (Multi-pass) Enable shader #2 \begin_inset Newline newline \end_inset Enable custom shader or use after rendering to FBO. \end_layout \begin_layout Itemize Shaders (Multi-pass) XML shder (2nd pass) \begin_inset Newline newline \end_inset Sets shader to use for second-pass. \end_layout \begin_layout Itemize Shaders (Multi-pass) FBO Scale \begin_inset Newline newline \end_inset Scale to use when rendering to FBO. \end_layout \begin_layout Itemize Shaders (Multi-pass) Second-pass bilinear filtering \begin_inset Newline newline \end_inset Use bilinear filtering on FBO texture on second pass. \end_layout \begin_layout Itemize Enable on-screen fonts \begin_inset Newline newline \end_inset Enable rendering of on-screen fonts for system messages. \end_layout \begin_layout Subsubsection Notes on shaders \end_layout \begin_layout Itemize The shaders that come prepackaged with RetroArch Android come from the PS3 and Xbox 360 ports of RetroArch. Unfortunately, most Android GPUs are very weak compared to the ones inside the PS3 and 360 - so most of these shaders will run extemely slow on nearly all Android devices right now. To make these shaders usable we will have to wait until GPUs on Android-powered devices catch up with PS3 and 360. They will make for good GPU benchmarks in the meantime - these shaders are far more intensive on the GPU than the trivial 'shaders' used in commercial games - which are mostly used for menial tasks instead of applying an expensive image-enhancing algorithm to the entire screen like the 'shader filters' seen here. \end_layout \begin_layout Subsubsection Notes on refresh rate \end_layout \begin_layout Itemize Some devices (like the Samsung Galaxy S3) falsely report that the screen refresh rate is 60Hz. For these devices, it is recommended that you set 'forced refresh rate' manually to a lower rate until you find the right value that gives you good audio/video with no audio pops. \end_layout \begin_layout Subsection Audio Settings \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename retroarch-android/UVU6Chp.png lyxscale 50 scale 35 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash caption{'Audio Settings' screen.} \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Itemize Audio Enable \begin_inset Newline newline \end_inset Uncheck this to disable sound. \end_layout \begin_layout Itemize Dynamic Rate Control \begin_inset Newline newline \end_inset Dynamic rate control tries to prevent sound pops by dynamically adjusting samplerate. It is recommended that you leave this on for RetroArch Android. \end_layout \begin_layout Subsection Input Settings \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash begin{figure} \backslash begin{centering} \end_layout \end_inset \begin_inset Graphics filename retroarch-android/deYDWvd.png lyxscale 50 scale 35 clip \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash caption{'Input Settings' screen.} \backslash end{centering} \backslash end{figure} \end_layout \end_inset \end_layout \begin_layout Itemize Configuration Autodetect Enable \begin_inset Newline newline \end_inset This will attempt to preconfigure various gamepads and/or IME apps that you connect. \end_layout \begin_layout Itemize Debug Input Reporting Enable \begin_inset Newline newline \end_inset This will report keycodes onscreen generated by your input device(s). You should use this option when you want us to support a gamepad that you use. You should use this option then to see which keycodes are generated by all the buttons on your gamepad/input device and then report this back to us. \end_layout \begin_layout Itemize Touchscreen Overlay Enable \begin_inset Newline newline \end_inset You can disable the overlay system entirely by disabling this. \end_layout \begin_layout Itemize Input overlay \begin_inset Newline newline \end_inset You can select a different overlay by choosing this option. \end_layout \begin_layout Section RetroArch on other platforms \end_layout \begin_layout Standard RetroArch isn't only available for Android. It is available on other platforms as well, including: \end_layout \begin_layout Itemize PlayStation3 \end_layout \begin_layout Itemize Xbox 1 \end_layout \begin_layout Itemize Xbox 360 \end_layout \begin_layout Itemize Wii/Gamecube \end_layout \begin_layout Itemize Raspberry Pi \end_layout \begin_layout Itemize PC (Mac/Linux/Windows) \end_layout \begin_layout Standard And it will be ported to even more platforms in the future. You might even see the libretro cores running in XBMC shortly. \end_layout \begin_layout Section About Us \end_layout \begin_layout Standard Homepage: \begin_inset Flex URL status collapsed \begin_layout Plain Layout http://www.libretro.org \end_layout \end_inset \begin_inset Newline newline \end_inset IRC: #retroarch at freenode \begin_inset Newline newline \end_inset Github (libretro organization): \begin_inset Flex URL status collapsed \begin_layout Plain Layout https://github.com/libretro \end_layout \end_inset \begin_inset Newline newline \end_inset RetroArch @ Github: \begin_inset Flex URL status collapsed \begin_layout Plain Layout https://github.com/Themaister/RetroArch \end_layout \end_inset \begin_inset Newline newline \end_inset Libretro @ Twitter: \begin_inset Flex URL status collapsed \begin_layout Plain Layout https://twitter.com/libretro \end_layout \end_inset \begin_inset Newline newline \end_inset Libretro @ Facebook: \begin_inset Flex URL status collapsed \begin_layout Plain Layout https://www.facebook.com/libretro.retroarch \end_layout \end_inset \end_layout \begin_layout Section Credits \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{RetroArch Android} \end_layout \end_inset \end_layout \begin_layout Standard Hans-Kristian Arntzen (Themaister) \end_layout \begin_layout Standard Daniel De Matteis (Squarepusher2/Twinaphex) \end_layout \begin_layout Standard Michael Lelli (ToadKing) \begin_inset Newline newline \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{RetroArch Android contributions} \end_layout \end_inset \end_layout \begin_layout Standard Meancoot \end_layout \begin_layout Standard Opium2k (overlay images) \begin_inset Newline newline \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash textbf{Thanks to} \end_layout \end_inset \end_layout \begin_layout Standard Notaz (PCSX ReARMed libretro port - RetroArch ARM Linux patches) \end_layout \begin_layout Standard FBA Team (for adopting libretro upstream - FBA) \end_layout \begin_layout Standard Ekeeke (for adopting libretro upstream - Genesis Plus GX) \end_layout \begin_layout Standard CaH4e3 (for adopting libretro upstream - FCEUmm) \end_layout \begin_layout Standard Rdanbrook (for adopting libretro upstream - NEStopia Undead) \end_layout \begin_layout Standard XBMC devs (for adopting libretro vis a vis RetroPlayer) \end_layout \begin_layout Standard Zeromus \end_layout \end_body \end_document ================================================ FILE: deploy ================================================ #!/bin/sh git fetch git reset --hard origin/master mkdocs build ================================================ FILE: docs/CNAME ================================================ docs.libretro.com ================================================ FILE: docs/development/bounties.md ================================================ # Libretro open source bounties !!! Info "What is an Open Source Bounty?" Bounties are usually offered as an incentive for fixing software bugs or implementing minor features. Bounty driven development is one of the Business models for open-source software. The compensation offered for an open-source bounty is usually small. Source: [Wikipedia](https://en.wikipedia.org/wiki/Open-source_bounty) ## Stages of the bounty process 1. Users fund bounties on open github issues or feature requests they want to see addressed. 2. Developers create solutions which closes the issues and claim the corresponding bounties on Bountysource. 3. Backers can accept or reject the claims. 4. If accepted, Bountysource pays the bounties to the developer. ## What is Bountysource? [Bountysource](http://bountysource.com/) is a funding platform for open-source software which allows users and developers to create bounties from any existing github issue. Libretro has no formal partnership with Bountysource and there is no requirement to use the Bountysource service. ## Who can post a bounty? Anybody with PayPal, Bitcoin, or funds in a Bountysource account (such as earning money from a previous bounty). ## What does it cost to post a bounty? There are no fees associated with posting a bounty. For example, to post a $5 bounty, you will be charged $5. For a $500 bounty, you will be charged $500. ## Do I have to be affiliated with libretro in order to put a bounty on an issue? No. Anybody can put a bounty on any issue, regardless of their relationship with the project. ## Do I have to be affiliated libretro in order to claim a bounty on an issue? No. ## Can several people claim the same bounty? Yes. When there are multiple claims on a bounty, the people who funded the bounty decide which of the solutions gets the bounty. When a bounty claim is submitted by a developer, the claim is put into a two week verification period. Backers are notified by email and can then accept or reject the claim. * If all Backers vote to accept the claim, it is processed immediately and the developer is awarded the bounty. * If any Backer fails to accept the claim, it remains in the two week waiting period. * If any Backer has an issue with the claim, they can reject it. Claims cannot be paid out until the dispute is resolved and the rejected status is lifted. ## Further Bountysource information You can find [a more comprehensive version of this information](https://github.com/bountysource/core/wiki/Frequently-Asked-Questions) and more directly from Bountysource. ================================================ FILE: docs/development/coding-standards.md ================================================ # Libretro Coding Standards !!! Note "Scope" These standards are intended to apply to frontends, cores, and other projects that are maintained as part of the Libretro organization. These standards are not enforced on independent projects making use of the Libretro API or other open technologies. ## Standards for RetroArch ### C89 Compatibility All code contributed to RetroArch must be compliant with the "C89" coding standard established by [ANSI X3.159-1989](https://web.archive.org/web/20110306044509/http://flash-gordon.me.uk/ansi.c.txt). #### Variable declaration To maintain C89 compatibility, declare all local variables at the beginning of their respective scope blocks, rather than inline at the time of their first use. #### Comments To maintain C89 compatibility, comments should be written in legacy using `/*` at the beginning and `*/` and the end. Sometimes it is useful to incorporate a lengthy comment in source. For example: - providing specifications for a function preceding its declaration - to explain a complex or unintuitive algorithm - to explain the history or special circumstances of a section of code - Comments use a maximum column width of 80 characters, and each new line of a multiline comment should begin with a space and an asterisk: ```c /** * Retrieves the sensor state associated with the provided port and ID. This * function pointer may be set to NULL if retreiving sensor state is not * supported. * * @param data The input state struct * @param port * @param id Sensor ID * * @return The current state associated with the port and ID as a float **/ float (*get_sensor_input)(void *data, unsigned port, unsigned id); ``` ### Indentation Indentation is three spaces. ### Braces Brace usage follows "Allman style". The brace associated with a control statement is placed on the following line, indented to the same level as the control statement. Statements within the braces are indented to the next level. ```c while (x == y) { something(); somethingelse(); } finalthing(); ``` ### Single-line `if` conditional statements `if` and `else` conditionals with single-line statements should be spaced with the conditional on one line and the statement below it, indented, with no braces: ```c if (time > launch_date) initiate_probe_communication(); else generate_prelaunch_report(); ``` ### Whitespace and alignment When possible, use whitespace to improve the readability of code that makes many assignment statements in a row, uses complex conditionals, or passes a large number of parameters to a function. **Example of aligning successive assignment statements**: ```c if (seq == 1157460427127406720ULL) { content_ctx_info_t content_info; content_info.argc = 0; content_info.argv = NULL; content_info.args = NULL; content_info.environ_get = NULL; } ``` **Example of aligning a complex parameter list**: ```c if (recording_driver_get_data_ptr()) { runloop_msg_queue_push( msg_hash_to_str(MSG_RESTARTING_RECORDING_DUE_TO_DRIVER_REINIT), 2, 180, false, NULL, MESSAGE_QUEUE_ICON_DEFAULT, MESSAGE_QUEUE_CATEGORY_INFO); command_event(CMD_EVENT_RECORD_DEINIT, NULL); command_event(CMD_EVENT_RECORD_INIT, NULL); } ``` ### Naming conventions #### naming typedefs typedefs should have the suffix `_t`. For example, the case of using `typedef` with a `struct`: ```c typedef struct input_driver_state { input_driver_t *current_driver; void *current_input_data; } input_driver_state_t; ``` #### Common RetroArch source abbreviations | Abbreviation | Meaning | | ------------- | -------------- | | ra, rarch | RetroArch | | av | Audio-Visual | | cb | Callback | | ctx | Context | | gfx | Graphics | | hw | Hardware | | idx | Index | | ptr | Pointer | | st | State | | sw | Software | | ui | User interface | ### vim configuration for Libretro style Coders who use the **vim** editor can create a `vimrc` configuration file with the following settings in order to pre-set RetroArch indentation style. ``` set tabstop=3 set shiftwidth=3 set expandtab set textwidth=80 ``` ## Standards for Libretro cores Cores and other projects that are maintained by the Libretro organization can be considered as three categories: * New, original software * Ports and enhancements of third-party software that is still maintained * Ports and enhancements of third-party software that is not maintained New cores and other projects **that are maintained by the Libretro organization** should be coded as closely to the Libretro/RetroArch standard as possible based on the language used by the core. Cores that are based on existing software should generally conform to whatever standards and style were used in the original software, unless the original software is no longer maintained. In that case the coding style may be changed to Libretro/RetroArch at the discretion of the involved Libretro developers and leadership. ================================================ FILE: docs/development/cores/core-options-translation.md ================================================ # Adding Translations ## Setting up translation with Crowdin The scripts and workflows referenced here, as well as some sample `core_options` files, can be found in the [RetroArch translation example](https://github.com/libretro/RetroArch/tree/master/libretro-common/samples/core_options/example_translation). ### Requirements Make sure the core is libretro conformant: both `libretro_core_options.h`, containing the English texts, and `libretro_core_options_intl.h`, containing all already existing translations, if any, must be present in the same directory. > Please note: `libretro_core_options_intl.h` does not need to contain anything, if no translations exist or none of them should be preserved. The scripts are not compatible with text filled in by macros or during run time. The procedure should not fail - but those texts will not be made translatable. Also, please verify the existence and correct use of `#ifdef HAVE_LANGEXTRA` and/or `#ifndef HAVE_NO_LANGEXTRA` pre-compiler instructions in `libretro_core_options.h` to remove any references to additional languages on platforms which cannot handle them, e.g. due to limited RAM. For an example, refer to an up-to-date core, like [gambatte-libretro](https://github.com/libretro/gambatte-libretro/blob/master/libgambatte/libretro/libretro_core_options.h). > Make sure `options_intl` in `libretro_core_options.h` correctly references the `_intl` options, or the translations will not be applied! ### Adding automatic Crowdin sync Place the `intl` and `.github` folders from the [sample folder](https://github.com/libretro/RetroArch/tree/master/libretro-common/samples/core_options/example_translation), including content, into the root of the repository. In `.github/workflows` are two files: `crowdin_prep.yml` & `crowdin_translate.yml`. In each of those are placeholders, which need to be replaced. For convenience, one can run `intl/activate.py`, which will try to find the `libretro_core_options.h` file as well as identify the core name to fill those placeholders with. Even then, one should still check if it produced the correct result: For `crowdin_prep.yml`: > **NOTE:** Please verify, that this workflow watches the correct branch (e.g. main, instead of master)! Uploads happen, whenever `libretro_core_options.h` of that branch is changed. - (x2) - replace with the full path from the root of the repo to the `libretro_core_options.h` file - - the name of the core (or repo) And for crowdin_translate.yml: - <0-59> <0-23> - Minute and hour at which the sync will happen. The script will generate a random time for this, to avoid stressing GitHub & Crowdin with many simultaneous runs. - - same as above - (x2) - replace with the full path from the root of the repo to the 'libretro_core_options_intl.h' file Create a Pull Request and ask a Crowdin project manager, either on [Crowdin](https://crowdin.com/project/retroarch) or, preferably, on [Discord](https://ra-link.web.app/discord) in the `retroarch-translations` channel, to provide you with an access token. Create an Actions repository secret on GitHub named CROWDIN_API_KEY for this access token. When everything is ready, run the "Crowdin Translations Initial Setup" workflow manually to upload the source texts and any translations to Crowdin. > You may either disable the initial workflow or even remove it from your repository. Running it more than once is very much discouraged! That may mess with the newest translations, which are usually not yet incorporated into the repository. Finally, it is recommended to run the "Crowdin Translation Sync" workflow manually once. If a "Permission to \ denied" error occurs, you might need to configure the GITHUB_TOKEN with the appropriate access rights, [see here](https://github.com/marketplace/actions/github-push#requirements-and-prerequisites). ### (For Crowdin project managers) Creating an access token To create an access token, navigate to the account settings via your profile picture in the top right. Change to the API tab. Here you should find a `New Token` button. Name the token after the core/repository, which will receive it. The following permissions should be set: - Projects - read - Source files & strings - read & write - Translations - read & write - (optional) Translation status - read > Please provide these access tokens to the core developers in a private message and delete those after successful setup. Do not share tokens publicly or store them in plain text long term! ## Enabling new languages in cores Adding a language to RetroArch does not automatically enable it for the core options. To do that for cores which have been added to Crowdin, follow these steps: 1. Locate the `libretro.h` file and add a `RETRO_LANGUAGE_XXXXX` item to the `retro_language` enum exactly the same as was done for RetroArch. - Alternatively, overwrite this file with the `libretro-common/include/libretro.h` file from RetroArch's code. 2. Locate the `libretro_core_options.h` file and open it. - Add `&options_xx,` at the end of the `options_intl` struct. Remember to keep the same order as in the `retro_language` enum. ### Example - mgba: - [Enable Indonesian, Swedish and Ukrainian localisations](https://github.com/libretro/mgba/commit/b0cdccc9ad2e5a8cd40ad4b9a3db1587d6f1560b) ================================================ FILE: docs/development/cores/core-specific/dolphin.md ================================================ # Nintendo Gamecube/Wii (Dolphin) ## Requirements - CMake ## How to compile (for Windows x64 - Visual Studio 2017) In addition to the requirement(s) listed above, you will also need Visual Studio 2017 installed in order for the following to work. Enter the following commands (from the Dolphin source directory): mkdir build cd build cmake .. -DLIBRETRO=ON -DENABLE_QT=0 -DCMAKE_BUILD_TYPE=Release -G"Visual Studio 15 2017 Win64" cmake --build . --target dolphin_libretro --config Release !!! Warning If it says 'Could not find named generator' or something to that effect, it means you might be using the wrong cmake version on Msys2/Mingw. Remove the regular 'cmake' package and try to install 'mingw-w64-x86_64-cmake' instead. ================================================ FILE: docs/development/cores/core-specific/flycast.md ================================================ # Sega Dreamcast/NAOMI (Flycast) ## Requirements - CMake ## How to compile (for Windows) Enter the following commands (from the Flycast source directory): ``` mkdir build cd build cmake -DLIBRETRO=ON -G "MinGW Makefiles" ``` ## How to compile (for Linux) Enter the following commands (from the Flycast source directory): ``` mkdir build cd build cmake -DLIBRETRO=ON -DCMAKE_POSITION_INDEPENDENT_CODE=TRUE ``` ## How to debug To debug the Flycast core in GDB, you need to insert the following inside gdb before running RetroArch: ``` handle SIGSEGV nostop noprint ``` ================================================ FILE: docs/development/cores/core-specific/ishiiruka.md ================================================ # Nintendo Gamecube/Wii (Ishiiruka) ## Requirements - CMake ## How to compile (for Windows x64 - Visual Studio 2017) In addition to the requirement(s) listed above, you will also need Visual Studio 2017 installed in order for the following to work. Enter the following commands (from the Ishiiruka source directory): mkdir build cd build cmake .. -DLIBRETRO=ON -DCMAKE_BUILD_TYPE=Release -G"Visual Studio 15 2017 Win64" cmake --build . --target ishiiruka_libretro --config Release !!! Warning If it says 'Could not find named generator' or something to that effect, it means you might be using the wrong cmake version on Msys2/Mingw. Remove the regular 'cmake' package and try to install 'mingw-w64-x86_64-cmake' instead. ================================================ FILE: docs/development/cores/core-specific/mame-2003-plus.md ================================================ # MAME 2003-Plus Development ## Build environment MAME 2003-Plus is generally compatible with the RetroArch build environments that can be found in the docs section `For Developers` -> `RetroArch` -> `Compilation Guides`. ## Submitting Control Names _Note: This first half of this section is written for users who cannot submit code themselves so that coders have the information necessary to assist. The second half is the process written from a coding perspective._ ### Background reference: controls.dat [As part of mame2003 we have an 'automated port' of the MAME 0.141 controls.dat project information](https://github.com/libretro/mame2003-plus-libretro/blob/master/src/controls.c). It address many, but not all games supported by mame2003-plus. Therefore in many cases adding new control labels can be as simple as adding the existing controls.dat metadata to a driver declaration. However as part of that process the controls.dat metadata needs to be checked in two ways before it can be added: 1. From the user perspective: are the control names actually correct 2. From the coder perspective: does the switch logic in the controls.dat naming function work as intended ### Users: Necessary Information #### Games affected Often clones and even different games that share the same hardware platform and operating system share the same control names. Please do as best you can to submit a complete list of all games which share the control names you are submitting so that it can be applied comprehensively. For example there are quite a few games in the CPS1 driver which use the same control labels as `sf2`, Street Fighter 2. In that driver, the `sf2` control labels are applied all games listed as being a clone of `sf2` or a clone of `sf2ce`. #### List of control names Please submit your list of control names in a plain text list following the format below with one name to a line and the control number on the left. #### Naming standard The standard we use for determining the proper text to use for the name is to refer to current MAME. That is considered the canonical reference. For example the button names for Street Fighter 2 would be submitted as: ``` BUTTON1: "Jab Punch" BUTTON2: "Strong Punch" BUTTON3: "Fierce Punch" BUTTON4: "Short Kick" BUTTON5: "Forward Kick" BUTTON6: "Roundhouse Kick" ``` ### Coders: Implementation Custom button names are added by creating a `ControlInfo` struct and a button label function in the driver such for _Street Fighter 2_ and its clones. **Note that in the button labeler function we prefix the name of the control with a macro like `BTN1`, `BTN2`, etc. so that there is a reference to the original MAME button number still visible in the libretro frontend.** #### Generic and custom joystick labels There are two generic joystick labeling functions available for control panels with joysticks that have no game-specific labels. `joy2way_labels` returns only generic `Left` and `Right` strings. `joy4way_labels` returns only generic `Left`, `Right`, `Up`, and `Down` strings for 4-way and 8-way joysticks An example of game-specific 8-way joystick labels is Street Fighter 2, which uses `Crouch` instead of `Down` and `Jump` instead of `Up`. Street Fighter 2 is therefore is not suitable for the generic function. #### Street Fighter 2 Example In this case, we were able to incorporate some of the **control.dat** metadata which populates the `st2_ctrl` struct: ```c const struct ControlInfo sf2_ctrl = { false, /* alternating_controls */ true, /* mirrored_controls */ "", /* control_details */ &sf2_get_btn }; const char *sf2_get_btn(int type) { switch(type) { /* P1NumButtons=6 */ case (IPT_OSD_DESCRIPTION): return "8-way Joystick+joy8way"; case IPT_BUTTON1: return BTN1 "Jab Punch"; case IPT_BUTTON2: return BTN2 "Strong Punch"; case IPT_BUTTON3: return BTN3 "Fierce Punch"; case IPT_BUTTON4: return BTN4 "Short Kick"; case IPT_BUTTON5: return BTN5 "Forward Kick"; case IPT_BUTTON6: return BTN6 "Roundhouse Kick"; case IPT_JOYSTICK_UP: return "Jump"; case IPT_JOYSTICK_DOWN: return "Crouch"; case IPT_JOYSTICK_LEFT: return "Left"; case IPT_JOYSTICK_RIGHT: return "Right"; } /* end of switch */ return generic_btn_label(type); } ``` #### Driver Declaration Then you indicate the change for the appropriate romsets by adding a new letter (`C`) to the macro name and adding a function pointer to the struct. **In other words, the `GAME` driver macro becomes `GAMEC`.** ##### Before: ```c GAME(1991, sf2, 0, sf2, sf2, cps1, ROT0, "Capcom", "Street Fighter II - The World Warrior (World 910522)" ) ``` ##### After: ```c GAMEC(1991, sf2, 0, sf2, sf2, cps1, ROT0, "Capcom", "Street Fighter II - The World Warrior (World 910522)", &sf2_ctrl, NULL ) ``` **Note that a `NULL` is also added to the end of the macro. That parameter is used for NVRAM bootstraps. The same driver macro is used for adding controls and bootstraps in order to avoid having more and more macros. If this game also had an NVRAM bootstrap, the bootstrap would be included rather than NULL.** #### Stone Ball Example In this case we do not currently have much control metadata, so the implementation is minimal: ```c const struct ControlInfo stonebal_ctrl = { false, /* alternating_controls */ false, /* mirrored_controls */ "", /* control__details */ &stonebal_get_btn }; const char *stonebal_get_btn(int type) { switch(type) { case IPT_BUTTON1: return BTN1 "Shoot/Fight"; case IPT_BUTTON2: return BTN2 "Pass/Tackle"; case IPT_BUTTON3: return BTN3 "Push"; } /* end of switch */ return generic_btn_label(type); } ``` #### Driver Declaration ##### Before: ```c GAME( 1994, stonebal, 0, stonebal, stonebal, stonebal, ROT0, "Art and Magic", "Stone Ball (4 Players)" ) GAME( 1994, stoneba2, stonebal, stonebal, stonebal, stonebal, ROT0, "Art and Magic", "Stone Ball (2 Players)" ) ``` ##### After: ```c GAMEC( 1994, stonebal, 0, stonebal, stonebal, stonebal, ROT0, "Art and Magic", "Stone Ball (4 Players)", &stonebal_ctrl, NULL ) GAMEC( 1994, stoneba2, stonebal, stonebal, stonebal, stonebal, ROT0, "Art and Magic", "Stone Ball (2 Players)", &stonebal_ctrl, NULL ) ``` **Note that a `NULL` is also added to the end of the macro. That parameter is used for NVRAM bootstraps. The same driver macro is used for adding controls and bootstraps in order to avoid having more and more macros. If this game also had an NVRAM bootstrap, the bootstrap would be included rather than NULL.** -------------------- ## Adding an NVRAM Bootstrap ### Purpose and criteria for bootstraps The purpose of the NVRAM bootstrap functionality is to create a good user experience the first time a game is booted. When the behavior of a game on its first boot is impossible for a new user to tell from a crash, then a bootstrap is in order. More specifically, the conditions for adding a bootstrap are: * It is not clear what the user needs to do to get into the game **or** * It is not reasonably possible for the user to get into the game using a SNES controller or arcade control panel ### Example commit This doc will use the process of adding an nvram bootstrap for the game "Run and Gun (US ver. UAB)" with the driver name `rungunu`. #### Step 1: Generate a working NVRAM file The exact process is game-specific. #### Step 2: Compile and execute bin2c ```bash git clone http://github.com/libretro/mame2003-plus-libretro cd mame2003-plus-libretro cd tools/bin2c make ./bin2c -o rungunu_bootstrap.c rungunu.nv ``` #### Output The generated output will look like this: ```c const unsigned char rungunu_nv_bytes[] = { 4, 38,251,217,146, 71, 85, 65, 66, 0, 16, 3, 7, 3, 0, 0, 0, 0, 0, 7, 7, 0, 7, 26, 1, 16, 26, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, }; const unsigned int rungunu_nv_length = 128; ``` ### Step 3: Create a bin2cFILE The next step is manual -- putting the data that bin2c generated into the format that the core uses: ```c struct bin2cFILE { const unsigned int length; const unsigned char data[]; }; ``` #### Resulting bootstrap structure ```c const struct bin2cFILE rungunu_bootstrap = { 128, { 4, 38,251,217,146, 71, 85, 65, 66, 0, 16, 3, 7, 3, 0, 0, 0, 0, 0, 7, 7, 0, 7, 26, 1, 16, 26, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, } }; ``` ### Step 4: Setup the various source files Add `rungunu_bootstrap` to `bootstrap.c` and `bootstrap.h`. If `rungun.c` didn't already include the necessary headers from a prior bootstrap project I would have needed to add: ```c #include "bootstrap.h" #include "inptport.h" ``` ### Step 5: Declare the bootstrap in the driver #### Original: ```c GAMEX( 1993, rungunu, 0, rng, rng, rng, ROT0, "Konami", "Run and Gun (US ver. UAB)", GAME_IMPERFECT_GRAPHICS | GAME_IMPERFECT_COLORS | GAME_IMPERFECT_SOUND ) ``` #### Bootstrapped: ```c GAMECX( 1993, rungunu, 0, rng, rng, rng, ROT0, "Konami", "Run and Gun (US ver. UAB)", GAME_IMPERFECT_GRAPHICS | GAME_IMPERFECT_COLORS | GAME_IMPERFECT_SOUND, &generic_ctrl, &rungun_bootstrap ) ``` !!! Important The newer driver macros that support setting the bootstrap pointer also need a button labeling function pointer. If there is no existing control name function, passing `&generic_ctrl` suffices. -------------------- ## Compiling a PR for testing **Note:** For purposes of this guide, replace `PR_NUMBER` with the literal number of the github Pull Request you are interested in testing. For example, if you are interested in testing out the Pull Request which implemented the libretro analog input API, you would substitute `PR_NUMBER` below with `590`, the PR number [for that request](https://github.com/libretro/mame2003-plus-libretro/pull/590). ### *nix or msys: ```shell git clone https://github.com/libretro/mame2003-plus-libretro.git patch -p1 -d mame2003-plus-libretro < <(wget -qO- https://patch-diff.githubusercontent.com/raw/libretro/mame2003-plus-libretro/pull/PR_NUMBER.diff) cd mame2003-plus-libretro make ``` **Note:** If you are using the standard libretro/RetroArch msys2 environment, you will first need to install `patch` with this command: ```shell pacman -S patch ``` ### RetroPie ```shell cd ~/RetroPie-Setup/ sudo ./retropie_packages.sh lr-mame2003-plus clean sudo ./retropie_packages.sh lr-mame2003-plus sources sudo patch -p1 -d tmp/build/lr-mame2003-plus < <(wget -qO- https://patch-diff.githubusercontent.com/raw/libretro/mame2003-plus-libretro/pull/PR_NUMBER.diff) rm 590.diff sudo ./retropie_packages.sh lr-mame2003-plus build sudo ./retropie_packages.sh lr-mame2003-plus build install ``` ================================================ FILE: docs/development/cores/core-specific/mame-2016.md ================================================ # MAME 2016 Developer Docs As of 2019, this libretro port of MAME (the libretro "OSD" in MAME parlance) is known to be rather messy. The plan is to rewrite it eventually. What follows here is a technical explanation of what libretro had to do to MAME's GENie build system in order to compile it as a shared library with the appropriate API exported to be used as a libretro core. ## The problem with a static library MAME OSD You're _not_ supposed to put the public API of a shared library into a static library, particularly if those symbols are "unused" by any other part of the shared library. In other words, while the libretro API is contained within the retro OSD, the file containing the public API (`libretro.c`) must not be stripped by the helpful linker trying to optimize for you. How you do that varies quite a bit by linker, and some of them such as GNU `ld` require the options be in a specific order. How to do that with GENie is not clear. To solve all of these issues at once, we leave libretro.c out of the OSD library and add it to the main MAME library directly. This requires adding an includedirs block for the directory containing libco's header and a files block containing `libretro.c`. These changes are near the bottom of the GENie project in `scripts/src/main.lua`. This is not a clean solution. It just happens to be the one that works across platforms without jumping through hoops for every linker that comes along. ## Other libretro GENie mods As mentioned above, near the bottom of `scripts/src/main.lua`, there's a chunk of libretro-related additions and overrides. You can spot it by searching for "BEGIN libretro overrides to MAME's GENie build". Most of what's there is pretty self-explanatory. It overrides MAME to build a shared library and includes processing for ARCH and platform, the two standard libretro build target variables, and includes the `libretro.c` file mentioned above. It could probably be split into its own file, but hasn't been thus far for simplicity. The only other addition is `scripts/src/osd/retro.lua` and its `cfg` file which isn't strictly necessary to be a separate file. Pretty standard stuff in there. The real work is in main.lua, and it's all contingent upon use of the libretro OSD to be as minimally invasive into MAME as possible. That's about it really. Compared to the old system, GENie is both much simpler and more complicated for us. More complicated because stuff is in so many different places. Simpler because modifying GENie rules like we have done makes for an incredibly shallow fork. ## Makefile.libretro There is still a pure Makefile named `Makefile.libretro`. It guesses the `ARCH` and platform variables if they're not defined, and it passes those (renaming ARCH in the process) along with the OSD and several other useful arguments to GENie. It's basically a major shortcut for the make command line which for our needs is pretty long. It's been tested building the "arcade" (used to be UME) and tiny targets, just pass `SUBTARGET=tiny` to `Makefile.libretro` to get the latter. ## Final thoughts MAME is a beast. It compiles to a 137MB .dylib on the Mac and a 172MB `.so` on Linux. Nonetheless, if its retro OSD weren't such a mess, it would be a good example of how to port something to libretro. Presently it still requires a fork, but the fork is perhaps the shallowest libretro fork we've got. And while not every decision the MAME developers have ever made could be considered optimal, the one thing they have done is insist that every external dependency they have is included in their source tree -- which is exactly what we need. MAME's GENie setup is complex, but that is because MAME is complex. GENie isn't difficult to figure out if you know a bit of lua. Indeed iKarith does not claim to fully understand GENie, but managed to modify the project to build a libretro core with only a few pointers (thanks balrog!) and a little grepping of 3rdparty/genie. ================================================ FILE: docs/development/cores/core-specific/mame.md ================================================ # MAME (0.181-current) Development ## Building libretro-mame ### Build environement #### Windows 1. [Install and configure the RetroArch msys2 build environment](../../retroarch/compilation/windows.md) 2. From the msys2 console, install python with the command `pacman -S python` ### Clone the repository ``` git clone http://github.com/libretro/mame cd mame ``` ### general `make` syntax | Build type | Command | | --- | --- | | Complete build | `make -f Makefile.libretro -j$(nproc)` | | Arcade-only build | `make -f Makefile.libretro -j$(nproc) SUBTARGET=arcade` | | Softlist-only build | `make -f Makefile.libretro -j$(nproc) SUBTARGET=mess` | ### Platform-specific `make` syntax | Platform | Command | | --- | --- | | 64-bit processors | `make -f Makefile.libretro -j$(nproc) PTR64=1` | ## Building a previous version !!! Important If you want to build a previous version of MAME, begin by making sure that you can build the most recent version. Once you have built the most recent version of MAME to establish that your build environment is complete, reset the contents of the repository to a clean state: ``` make clean git reset --hard ``` !!! Warning These commands will delete any files in your `mame` subfolder that are not in the `libretro/mame` github repository. ### `checkout` the previous version source See the section "Commit hashes for previous versions" below to find the correct commit hash. For example, if you wish to build MAME 0.205, the corresponding commit hash is `b691c38`. Use this commit hash and the `git checkout` command to roll back the source to your chosen version: ``` git checkout b691c38 ``` ## Commit hashes for previous versions | Version | Commit | | -------- | ------- | | mame0216 | 7cf10a3 | | mame0207 | 40fc339 | | mame0206 | cf02fe3 | | mame0205 | b691c38 | | mame0204 | c6150e7 | | mame0203 | b57a140 | | mame0202 | 856478f | | mame0201 | 4dc302e | | mame0200 | ff19cd3 | | mame0199 | f2e805a | | mame0198 | c5f6a62 | | mame0197 | 74293f8 | | mame0196 | e8f2016 | | mame0195 | e44e85b | | mame0194 | 5be2496 | | mame0193 | bf28b34 | | mame0192 | d771f54 | | mame0191 | a5db728 | | mame0190 | f57574c | | mame0189 | 2beedc5 | | mame0188 | 7b45ec1 | | mame0187 | 1d9648b | | mame0186 | e4c6cb1 | | mame0185 | fe01a13 | | mame0184 | 7768128 | | mame0183 | 4ee22dc | | mame0182 | 22c42ab | | mame0181 | 3a1651e | ================================================ FILE: docs/development/cores/core-specific/pcsx2.md ================================================ # Sony PlayStation2 (LRPS2) ## Requirements - CMake - xxd (optional) ## How to compile (for Windows x64 - Visual Studio 2017) In addition to the requirement(s) listed above, you will also need Visual Studio 2017 installed in order for the following to work. Enter the following commands (from the PCSX2 source directory): mkdir build cd build cmake .. -DLIBRETRO=ON -DCMAKE_BUILD_TYPE=Release -G"Visual Studio 15 2017 Win64" cmake --build . --target pcsx2_libretro --config Release !!! Warning If it says 'Could not find named generator' or something to that effect, it means you might be using the wrong cmake version on Msys2/Mingw. Remove the regular 'cmake' package and try to install 'mingw-w64-x86_64-cmake' instead. !!! Warning If you get this error 'Visual Studio 15 2017 could not find any instance of Visual Studio', your installation of Visual Studio 2017 is most likely missing 'Visual C++ tools for CMake'. This can be found under 'Desktop development with C++'. Go back to Visual Studio 2017 and install this, then try again. ## How to compile (for Windows x64 - Visual Studio 2019) In addition to the requirement(s) listed above, you will also need Visual Studio 2019 installed in order for the following to work. Enter the following commands (from the PCSX2 source directory): mkdir build cd build cmake .. -DLIBRETRO=ON -G"Visual Studio 16 2019" cmake --build . --target pcsx2_libretro --config Release !!! Warning If it says 'Could not find named generator' or something to that effect, it means you might be using the wrong cmake version on Msys2/Mingw. Remove the regular 'cmake' package and try to install 'mingw-w64-x86_64-cmake' instead. ## How to compile (for Windows x64 - Visual Studio 2022) In addition to the requirement(s) listed above, you will also need Visual Studio 2022 installed in order for the following to work. Enter the following commands (from the PCSX2 source directory): cmake -B build -G "Visual Studio 17 2022" -DCMAKE_BUILD_TYPE=Release -DLIBRETRO=ON cmake --build build --config Release --target pcsx2_libretro ## How to compile (for Linux) Enter the following commands (from the PCSX2 source directory): mkdir build cd build cmake .. make ================================================ FILE: docs/development/cores/core-specific/swanstation.md ================================================ # Sony PlayStation (SwanStation) ## Requirements - CMake ## How to compile (for Windows x64 - Visual Studio 2019) In addition to the requirement(s) listed above, you will also need Visual Studio 2019 installed in order for the following to work. Enter the following commands (from the SwanStation source directory): mkdir build cd build cmake -G "Visual Studio 16 2019" -A "x64" -DCMAKE_BUILD_TYPE=Release .. cmake --build . --target swanstation_libretro --config Release !!! Warning If it says 'Could not find named generator' or something to that effect, it means you might be using the wrong cmake version on Msys2/Mingw. Remove the regular 'cmake' package and try to install 'mingw-w64-x86_64-cmake' instead. ================================================ FILE: docs/development/cores/developing-cores.md ================================================ # Developing Libretro Cores ### Libretro API The Libretro API is a lightweight C-based Application Programming Interface (API) that exposes generic audio, video, and input callbacks. Developers of "cores" such as standalone games, game emulators, media players, and other applications don’t have to worry about writing different video drivers for Direct3D, OpenGL or worrying about catering to all possible input APIs, sound APIs, gamepads, etc. When you choose to use the libretro API, your program gets turned into a single library file (called a ‘libretro core’). A frontend that supports the libretro API can then load that library file and run the app. The frontend’s responsibility is to provide all the implementation-specific details. The libretro core’s responsibility is solely to provide the main program. Any project that is ported to work with this API can be made to run on ANY libretro frontend – now and forever. You maintain a single codebase that only deals with the main program, and you then target one single API (libretro) in order to port your program over to multiple platforms at once. A libretro core written in portable C or C++ can run seamlessly on many platforms with very little or no porting effort. Libretro bindings for other languages are growing increasingly common and comprehensive as well. !!! info "Licensing" Libretro is an open specification that is 100% free to implement, with no licensing fees or strings attached. Our reference frontend is RetroArch. The two projects are not the same, and this is reflected in the licensing. RetroArch is licensed via GPLv3 whereas the libretro API is a MIT-licensed API. ## Resources for core development ### Canonical `libretro.h` The [most current canonical copy of `libretro.h`](https://raw.githubusercontent.com/libretro/libretro-common/master/include/libretro.h) can be found in the master branch of the libretro-common repository. !!! tip `libretro.h` is the single most important technical reference for developers of libretro cores and frontends ### `skeletor` sample core RetroArch contributor **bparker06** created [`skeletor`](https://github.com/libretro/skeletor) as a minimal libretro core implementation. `skeletor` can also be useful by furnishing the stub libretro `Makefile` and `Makefile.common` files. ### Development log of Libretro cores Thank you for those blog posts : **Beardypig** published a two-part guide ([Part 1](https://web.archive.org/web/20190219134430/http://www.beardypig.com/2016/01/15/emulator-build-along-1/), [Part 2](https://web.archive.org/web/20190219134028/http://www.beardypig.com/2016/01/22/emulator-build-along-2/)) describing the process of implementing `libretro.h` as part of creating [Vectrexia](https://github.com/beardypig/vectrexia-emulator/), an original emulator core designed for libretro from the ground up. **James Roeder** has written a seven parts blog posts entitled [An Arduous Endeavor](https://www.jroeder.net/2021/08/10/arduous-endeavor-part-1/). **Natesh** has written a blog post about [GameboyCore as a libretro core](https://nnarain.github.io/2017/07/13/GameboyCore-as-a-libretro-core!.html). ### `libretro-common` [`libretro-common`](https://github.com/libretro/libretro-common/) is a collection of essential cross-platform coding blocks useful for libretro core and frontend development, written primarily in C. Permissively licensed. ### `libretro-deps` [`libretro-deps`](https://github.com/libretro/libretro-deps/) is a collection of third-party dependencies, pre-modified for use by libretro cores. ### `libretro-samples` [`libretro-samples`](https://github.com/libretro/libretro-samples) is a set of illustrations of the libretro API. ### OpenGL hardware accelerated cores [A guide for developing OpenGL accelerated cores](opengl-cores.md) is available. ## Implementing the API The libretro API consists of several functions outlined in libretro.h, found in the RetroArch source package. A libretro implementation should be compiled into a dynamically loadable executable (.dll/.so/.dylib) or a static library (.a/.lib) that exports all the functions outlined in libretro.h. These will be called by the frontend. Implementations are designed to be single-instance, so global state is allowed. Should the frontend call these functions in wrong order, undefined behavior occurs. The API header is compatible with C99 and C++. From C99, the bool type and are used. The program flow of a frontend using the libretro API can be expressed as follows: ### Startup #### `retro_api_version()` This function should return RETRO_API_VERSION, defined in libretro.h. It is used by the frontend to determine if ABI/API are mismatched. The ver- sion will be bumped should there be any non- compatible changes to the API. Changes to retro_* structures, as well as changes in publically visible functions and/or their arguments will warrant a bump in API version. #### `retro_set_*()` Libretro is callback based. The frontend will set all callbacks at this stage, and the implementation must store these function pointers somewhere. The frontend can, at a later stage, call these. #### `retro_init()` This function is called once, and gives the implementation a chance to initialize data structures. #### Environment callback While libretro has callbacks for video, audio and input, there’s a callback type dubbed the environment callback. This callback (`retro_environment_t`) is a generic way for the libretro implementation to access features of the API that are considered too obscure to deserve its own symbols. It can be extended without breaking ABI. The callback has a return type of `bool` which tells if the frontend recognized the request given to it. #### `retro_set_controller_port_device()` By default, gamepads will be assumed to be inserted into the implementation. If the engine is sensitive to which type of input device is plugged in, the frontend may call this function to set the device to be used for a certain player. The implementation should try to auto-detect this if possible. #### `retro_get_system_info()` The frontend will typically request statically known information about the core such as the name of the implementation, version number, etc. The information returned must be allocated statically. #### `retro_load_game()` This function will load content. If the implementation is an emulator, this would be a game ROM image, if it is a game engine, this could be packaged upassets for the game, etc. The function takes a structure that points to the path where the ROM was loaded from, as well as a memory chunk of the already loaded file. **There are two modes of loading files with libretro.** If the game engine requires to know the path of where the ROM image was loaded from, the `need_fullpath` field in `retro_system_info` must be set to true. If the path is required, the frontend will not load the file into the data/size fields, and it is up to the implementation to load the file from disk. The path might be both relative and absolute, and the implementation must check for both cases. This is useful if the ROM image is too large to load into memory at once. It is also useful if the assests consist of many smaller files, where it is necessary to know the path of a master file to infer the paths of the others. If `need_fullpath` is set to `false`, the frontend will load the ROM image into memory beforehand. In this mode, the path field is not guaranteed to be non-`NULL`. It should point to a valid path if the file was indeed, loaded from disk, however, it is possible that the file was loaded from `stdin`, or similar, which has no well-defined path. It is recommended that `need_fullpath` is set to `false` if possible, as it allows more features, such as soft-patching to work correctly. #### `retro_get_system_av_info()` This function lets the frontend know essential audio/video properties of the game. As this information can depend on the game being loaded, this info will only be queried after a valid ROM image has been loaded. It is important to accurately report FPS and audio sampling rates, as FFmpeg recording relies on exact information to be able to run in sync for several hours. ### Running #### `retro_run()` After a game has been loaded successfully, retro_run() will be called repeatedly as long as the user desires. When called, the implementation will perform its inner functionality for one video frame. During this time, the implementation is free to call callbacks for video frames, audio samples, as well as polling input, and querying current input state. The requirements for the callbacks are that video callback is called exactly once, i.e. it does not have to come last. Also, input polling must be called at least once. #### Input Abstracting gamepad and other input devices is the hardest part of defining a multi-system API as it differs across every system. The libretro API therefore provides the RetroPad -- a gamepad/joystick abstraction available with digital and analog controls -- to allow cores to be written without platform-specific input code. Input device abstractions are also available for keyboards, mice, pointers, and lightguns. **Learn more in the [Input API](../input-api.md) docs.** #### Video/Audio synchronization considerations Libretro is based on fixed rates; video FPS and audio sampling rates are always assumed to be constant. Frontends will have control of the speed of playing, typically using VSync to obtain correctspeed. The frontend is free to "fast-forward", i.e. play as fast as possible without waiting, or slow-motion. For this reason, the engine should not rely on system timers to perform arbitrary synchronization. This is common and often needed in 3D games to account for varying frame rates while still maintaining a playable game. However, libretro targets classic systems where one can assume that 100% real-time performance will always be met, thus avoiding the need for careful timing code. By default, the libretro implementation should replace any arbitrary `sleep()` and `time()` patterns with simply calling video/audio callbacks. The frontend will make sure to apply the proper synchronization. This is mostly a problem with game ports, such as PrBoom. For the libretro port of PrBoom, which heavily relied on timers and sleeping patterns, sleeping was replaced with simply running for one frame, and calling the video callback. After that, enough audio was rendered to correspond to one frames worth of time, 1/fps seconds. All sleeping and timing patterns could be removed, and synchronization was correct. #### Audio callback options The libretro API has two different audio callbacks. Only one of these should be used; the implementation must choose which callback is best suited. One _audio frame_ is always made up of 2 int16_t samples, corresponding to the left and right channels, respectively. ##### Per-sample audio The first audio callback is called _per-sample_, but actually deals with a single _audio frame_. It has the prototype `void (*retro_audio_sample_t)(int16_t left, int16_t right)`. This should be used if the implementation generates a single audio frame at a time. The frontend will make sure to partition the audio data into suitable chunks to avoid incurring too much syscall overhead. ##### Batch audio If audio is output in a "batch" fashion, i.e. 1 / fps seconds worth of audio data at a time, the batch approach should be considered. Rather than looping over all audio frames and calling the per-sample callback every time, the _batch callback_ should be used instead. Its prototype is `size_t (*retro_audio_sample_batch_t)(const int16_t * samples, size_t num_frames)`. The number of samples should be `2 * num_frames`, with left and right channels interleaved every frame. Using the batch callback, audio will not be copied in a temporary buffer, which can buy a slight performance gain. Also, all data will be pushed to audio driver in one go, saving some slight overhead. It is not recommended to use the batch callback for very small (< 32 frames) amounts of data. The data passed to the batch callback should, if possible, be aligned to 16 bytes (depends on platform), to allow accelerated SIMD operations on audio. #### `retro_serialize_size()`, `retro_serialize()`, and `retro_unserialize()` Serialization is optional to implement. Serialization is better known as "save states" in emulators, and these functions are certainly more useful in emulators which have a fixed amount of state. It allows the frontend to take a snapshot of all internal state, and later restore it. This functionality is used to implement e.g. rewind and netplay. Some important considerations must be taken to implement these functions well: * If serialization is not supported, `retro_serialize_size()` should return 0. If retro_serialize_size() returns non-zero, it is assumed that serialization is properly implemented. * The frontend should call `retro_serialize_size()` before calling `retro_serialize()` to determine the amount of memory needed to correctly serialize. * The size eventually passed to `retro_serialize()` must be at least the size of the value returned in `retro_serialize_size()`. If too large a buffer is passed to `retro_serialize()`, the extra data should be ignored (or `memset` to 0). * It is valid for the value returned by `retro_serialize_size()` to vary over time, however, it cannot ever increase over time. If it should ever change, it must decrease. This is rationalized by the ability to predetermined a fixed save state size right after `retro_load_game()` that will always be large enough to hold any following serialization. This certainty is fundamental to the rewind implementation. This requirement only holds between calls to `retro_load_game()` and `retro_unload_game()`. If possible, the implementation should attempt to serialize data at consistent offsets in the memory buffer. This will greatly help the rewind implementation in RetroArch to use less memory. Both `retro_serialize()` and `retro_unserialize()` return a boolean value to let the frontend know if the implementation succeeded in serializing or unserializing. ### Tear-down #### `retro_unload_game()` After the user desired to stop playing, `retro_unload_game()` will be called. This should free any internal data related to the game, and allow `retro_load_game()` to be called again. #### `retro_deinit()` This function should free all state that was initialized during `retro_init()`. After calling this function, the frontend can again call `retro_init()`. ### Thread safety The libretro API does not make guarantees about thread safety. Therefore the core developer should assume the functions declared in the libretro header are neither reentrant nor safe to be called by multiple threads at the same time. If a core is multi-threaded then the core developer is responsible for thread safety when making libretro API calls. It is discouraged to do libretro API calls outside of `retro_run()` i.e. outside of the main thread. ## Add your core to Libretro infrastructure There are several steps before your core can be available to user via the Online Updater > Core Downloader : 1. Add your Libretro core info to [libretro-super repository](https://github.com/libretro/libretro-super/tree/master/dist/info) - As a test, place info file to `libretro_info_path`, load core, and validate if information shows up correctly: Information / Core Information 2. Add [.gitlab-ci.yml](https://github.com/search?q=org%3Alibretro+.gitlab-ci.yml&type=commits) to the root directory of your source code so it can be added to Libretro CI/CD. 3. If you want your core to be compatible with [RetroArch's playlist](/guides/roms-playlists-thumbnails) : - Add at least icons playlist and content for your core in [RetroArch assets repository](https://github.com/libretro/retroarch-assets/tree/master/src/xmb/monochrome) - Add your games to [Libretro database](https://github.com/libretro/libretro-database). 4. Add documentation of your core following the instructions in [libretro-docs](https://github.com/libretro/docs#adding-a-new-core). ================================================ FILE: docs/development/cores/dynamic-rate-control.md ================================================ # Dynamic Rate Control for Retro Game Emulators Dynamic Rate Control allows emulator frontends to synchronize both audio and video output at the same time, even when the emulating system has a different refresh rate and audio sampling rate than the gaming system that is being emulated. The method works by dynamically adjusting audio resampling ratios in such ways that ideally, the audio buffer is never underrun nor overrun, thus avoiding blocking on audio. This in turn allows vertical synchronization for video. The audio pitch is adjusted when adjusting audio resampling ratios, but in practice so little, that it is inaudible to the human ear. !!! Tip "Read this documentation in PDF form" Because the formulas in this documentation have not yet been converted to markdown, [please consult the original PDF version](https://github.com/libretro/docs/blob/master/archive/ratecontrol.pdf). _If you can assist in the conversion, please post an issue or PR in [the libretro documentation repository](https://github.com/libretro/docs)._ Retro games are highly synchronous. Their audio output rates are linked directly to video refresh rates. Every video frame, the audio chip generates on average a fixed amount of audio samples. Before continuing to emulate the next frame, the generated audio samples must be pushed to an audio buffer of fixed size. If there is not enough space in the audio buffer, the emulator must wait (block) for the buffer to become ready for writing. This is a non-ideal situation as while the emulator is blocking on audio, a vertical refresh might be missed entirely, thus creating stuttering video. ## Ideal synchronization For an emulator of a retro game system, a key factor in smooth video is vertical refresh synchronization (**VSync**), where each frame of the game maps to a single frame on the monitor. Audio must also be pushed to the speakers without any audio dropouts. This double synchronization requirement poses a problem as any form of synchronization to one modality will negatively affect the other. This is a real problem as an emulator has no way of guaranteeing perfectly equal video refresh rates and audio sampling rates as the original system. On conventional computer hardware, there is no perfect way of knowing the real monitor refresh rates and audio sampling rates either due to tolerances on oscillators. ## Scope of method As this method aims to implement a method for synchronization when VSync is used, this method is only useful when game frame rate is close to monitor frame rate. If this is not the case, other methods should be employed. ## Method This method assumes that audio from the emulator is output at regular intervals, e.g. every video frame. The method also assumes that audio is resampled from the game system sampling rate to the sound cards sampling rate. The resampling ratio will be dynamically adjusted every time audio is resampled and subsequently pushed to the audio buffer. ## Link to full version Because the formulas in this documentation have not yet been converted to markdown, [please consult the original PDF version](https://github.com/libretro/docs/blob/master/archive/ratecontrol.pdf). _If you can assist in the conversion, please post an issue or PR in [the libretro documentation repository](https://github.com/libretro/docs)._ ================================================ FILE: docs/development/cores/opengl-cores.md ================================================ # Use case for Libretro OpenGL API ### What do most modern platforms have in common? **Answer**: OpenGL or OpenGL ES. These APIs allow us to write 3D graphics-based applications: * In a platform-agnostic way * With hardware acceleration * Using a standard language/API ### What do these platforms not have in common? * Audio * Input * Shader * Windowing implementations * User interfaces * Touchscreen overlays * Camera * Sensors * Development environments ### What is not portable about OpenGL? * Symbol wrapper lookup (necessary on Windows) * Divergent subsets of API functionality (GLES 1/2/3, GL 1.5/2/3/4) * Windowing interfacing context drivers per platform * Display frontend for each platform * Post-processing by way of shaders Libretro's OpenGL implementation is designed specifically to address the practicalities of extending OpenGL and OpenGL ES hardware acceleration to the wide variety of architectures and environments supported by the libretro ecosystem. # Implementing OpenGL accelerated cores Libretro GL provides a portable solution for OpenGL-based hardware acceleration along with the rest of libretro's simple but comprehensive API. The Libretro API allows cores to use OpenGL (GL2+ or GLES2) directly in addition to frontend features, such as multi-pass shaders. This is accomplished by letting cores render to frame buffer objects (FBOs) instead of the back buffer. !!! important GL drivers must support render-to-texture extensions for this to work. ## Application model Using OpenGL in a libretro context is somewhat different than when you use libraries like SDL, GLFW or SFML. In libretro, the frontend owns the OpenGL context. For an application using conventional libraries like SDL, the application will do this: - Initialize, create a window of specific size - Initialize OpenGL resources - Per frame, handle window events (resize), handle input, render as desired, swap buffers - Tear down context and window Using libretro API, platform specifics like managing windows, rendering surfaces and input are all handled by the frontend. The core will only deal with rendering to a surface. The core renders to an FBO of fixed size, determined by the core. The frontend takes this rendered data and stretches to screen as desired by the user. It can apply shaders, change aspect ratio, etc. This model is equivalent to software rendering where `retro_video_refresh_t_callback` is called. ## Using OpenGL in libretro - Use `RETRO_ENVIRONMENT_SET_PIXEL_FORMAT` and request a 32-bit format. This is the format that the resulting framebuffer will have. In reality, RetroArch converts all 16-bit data (`RETRO_PIXEL_FORMAT_RGB565`) to 32-bit (`XRGB8888`) when running desktop GL for performance reasons. In GLES mode, this is not done, however. Do not rely on this behavior, and be explicit about it. - Use `RETRO_ENVIRONMENT_SET_HW_RENDER` environment callback in `retro_load_game()`, notifying frontend that core is using hardware rendering. An OpenGL 2+ or GLES2 context can be specified here. If this is not supported the callback will return false, and you can fallback to software rendering or refuse to start. - In `retro_get_system_av_info()`, as normal, `max_width` and `max_height` fields specify the maximum resolution the core will render to. - When the frontend has created a context or reset the context, `retro_hw_context_reset_t` is called. Here, OpenGL resources can be initialized. The frontend can reset the context at will (e.g. when changing from fullscreen to windowed mode and vice versa). The core should take this into account. It will be notified when reinitialization needs to happen. - A callback to grab OpenGL symbols is exposed via `retro_hw_get_proc_address_t`. Use this to retrieve symbols and extensions. - In `retro_run()`, use `retro_hw_get_current_framebuffer_t` callback to get which FBO to render to, e.g. `glBindFramebuffer(GL_FRAMEBUFFER, get_current_framebuffer())`. This is your "backbuffer". Do not attempt to render to the real backbuffer. You must call this every frame as it can change every frame. The dimensions of this FBO are at least as big as declared in `max_width` and `max_height`. If desired, the FBO also has a depth buffer attached (see `RETRO_ENVIRONMENT_SET_HW_RENDER`). - When done rendering, call `retro_video_refresh_t` with the macro `RETRO_HW_FRAMEBUFFER_VALID` as argument for buffer. Width and height should be specified as well, but pitch argument is irrelevant and will be ignored. If the frame is duped (see `RETRO_ENVIRONMENT_CAN_DUPE`), the buffer argument takes`NULL` as normal. ## Important considerations in the OpenGL code The frontend and libretro core share OpenGL context state. Some considerations have to be taken into account for this cooperation to work nicely. - Don’t leave buffers and global objects bound when calling `retro_video_refresh_t`. Make sure to unbind everything, i.e. VAOs, VBOs, shader programs, textures, etc. Failing to do this could potentially hit strange bugs. The frontend will also follow this rule to avoid clashes. Being tidy here is considered good practice anyway. - The GL viewport will be modified by frontend as well as libretro core. Set this every frame. - `glEnable()` state like depth testing, etc, is likely to be disabled in frontend as it's just rendering a quad to screen. Enable this per-frame if you use depth testing. There is no need to disable this before calling `retro_video_refresh_t`. - Avoid VAOs. They tend to break on less-than-stellar drivers, such as AMD drivers on Windows as of 2013 - Try to write code which is GLES2 as well as GL2+ (w/ extensions) compliant. This ensures maximum target surface for the libretro core. - Libretro treats top-left as origin. OpenGL treats bottom-left as origin. To be compatible with the libretro model, top-left semantics are preserved. Rendering normally will cause the image to be flipped vertically. To avoid this, simply scale the final projection matrix by `[1,− 1 , 1 ,1]`. ## Test implementations * [Several OpenGL demonstrations are available in `libretro-samples`](https://github.com/libretro/libretro-samples/tree/master/video/opengl) * [A demonstration OpenGL core is available](https://bitbucket.org/Themaister/libretro-gl) which uses instanced rendering of a textured cube, with FPS-style fly-by camera and libretro’s mouse API as well. It is valid GLES and GL2 at the same time. ## Building a libretro core Libretro is an interface, and not a utility library. Libretro cores are built as standalone dynamic or static libraries, and as they use GL symbols here, they must link against GL symbols themselves. An example of how this can be done is shown in [the test implementation](https://github.com/Themaister/RetroArch/blob/master/libretro-test-gl/Makefile). ================================================ FILE: docs/development/frontends.md ================================================ # Frontend Development Libretro frontends are programs that have implemented the [libretro API](libretro-overview.md) specification. If fully implemented, this allows the program to run any libretro core that has been developed. ## Frontend Development Guides * [A Libretro retrospective](https://web.archive.org/web/20190404052149/https://genodians.org/ehmry/2019-03-28-libretro) - Developer Emery Hemingway's detailed look back on implementing a new libretro frontend for the Genode Operating System. ## Reference frontend [RetroArch](http://retroarch.com) is the official reference [libretro](http://libretro.com) frontend, developed in-house. It is usually the first in implementing new features added to the libretro API. Written almost entirely in C, targets a large amount of platforms. Name | Author(s) | Description ------|-----------|------------ [Anarchy Arcade](http://store.steampowered.com/app/266430/Anarchy_Arcade/) | Elijah Newman-Gomez | AArcade is a virtual reality 3D desktop that launches shortcuts to absolutely anything you like. [Arcan](https://github.com/letoram/arcan) | Letoram | Powerful development framework for creating virtually anything from user interfaces for specialized embedded applications all the way to full-blown standalone desktop environments. [EmuHawk (BizHawk)](github.com/TASEmulators/BizHawk) | BizHawk team | Multi-system emulator that uses its own set of cores, but also allows loading libretro cores [to varied success](https://github.com/TASEmulators/BizHawk/wiki/Libretro-core-compatibility). [Emutest](https://github.com/kivutar/emutest) | kivutar | A headless libretro frontend to test libretro cores. [EmuVR](http://www.emuvr.net/about/) | | | [Hackable console](https://github.com/leiradel/hackable-console) | leiradel | Debugging tool for libretro cores. [Haiyajan](https://projects.deltabeard.com/haiyajan) | deltabeard | A tiny and fast libretro entertainment application. [KRetro](https://invent.kde.org/games/kretro) | Seshan Ravikumar | libretro emulation frontend for Plasma. [Ludo](https://github.com/libretro/ludo) | kivutar | libretro frontend written in Go. [Lemuroid](https://github.com/Swordfish90/Lemuroid) | Swordfish90 | All in 1 emulator on Android. [Merton](https://github.com/snowcone-ltd/merton) | Snowcone Ltd. | Merton is a work-in-progress emulator frontend for libretro built with [libmatoya](https://github.com/snowcone-ltd/libmatoya). [Mininal reference fronted](https://github.com/bparker06/reference_frontend) | bparker06 | This is a barebones minimal reference frontend for the libretro API. [minir](https://github.com/Alcaro/minir) | Alcaro | WIMP interface (Windows, Icons, Menus and Pointers), and only cares about the major desktop OSes. Drops flexibility in favor of improved out-of-the-box experience. [minir test fronts](https://github.com/Alcaro/minir/tree/master/subproj) | Alcaro | Three different fronts, none of which has IO drivers: retroprofile just runs the core, intended for performance tests and PGO; retrorepeat runs the core twice, expecting identical output; retrostateverify traces the entire core and verifies whether its savestates are perfect. [miniretro](https://github.com/davidgfnet/miniretro) | davidgfnet | This is a small (Linux only for now) CLI libretro frontend for automated testing of libretro cores. [nanoarch](https://github.com/heuripedes/nanoarch) | heuripedes | Small frontend providing video, audio and basic input features to run non-libretro-GL cores. Built on GLFW. [New Retro Arcade](http://digitalcybercherries.com/) | Digital Cyber Cherries | | [noarch](https://github.com/robloach/noarch) | RobLoach | Minimalist frontend which does not provide video, audio or even basic input. It loads a libretro core, runs an iteration, and then exits. Good for unit testing. [picoarch](https://git.crowdedwood.com/picoarch/about) | neonloop | picoarch uses libpicofe and SDL to create a small frontend to libretro cores. It's designed for small (320x240 2.0-2.4") screen, low-powered devices like the Trimui Model S (PowKiddy A66). [Phoenix](http://phoenix.vg/) | Phoenix | Upcoming libretro frontend written with the Qt5 cross-platform application framework. [raylib-libretro](https://github.com/RobLoach/raylib-libretro) | RobLoach | Libretro frontend using raylib. [retro_frontend](https://github.com/ehmry/genode-libretro) | Ehmry | Frontend for the [Genode](http://genode.org) operating system framework. Following the Genode philosophy this frontend strives to be a minimal implemention that is extensible via the abstract OS services provided to it. [RePlay OS](https://www.replayos.com/) | RTA | Upcoming libretro based frontend optimized for use with Raspberry Pi boards using both LCD and CRT screens. [replay](https://github.com/avojak/replay) | avojak | Native Linux multi-system emulator built in Vala and GTK for elementary OS. [Retrobot](https://github.com/rossimo/retrobot) | Ross Squires | A self-hosted Discord bot that allows friends to play games over chat. [RetroPlayer](https://forum.kodi.tv/forumdisplay.php?fid=194) | Kodi-Game | Also known as [Kodi-Game](https://github.com/kodi-game/), RetroPlayer is a libretro compatibility layer for [Kodi](https://kodi.tv/). [sdlarch](https://github.com/heuripedes/sdlarch) | heuripedes | Small frontend providing video, audio and basic input to run basic libretro cores. Built on SDL. [URetro](https://github.com/QuarkTheAwesome/URetro) | | Nintendo WiiU frontend [Vintage Simulator](https://vintagesimulator.com) | runvnc | 3D Lua-programmable libretro frontend supporting many 3D formats, some Cairo graphics, physics, emulation control with scripts [ZMZ](https://github.com/Alcaro/ZMZ) | Alcaro | Abandoned | Fork of [ZSNES](http://www.zsnes.com/) that rips out its emulation code, using libretro instead. Due to ZSNES being inflexible, ZMZ became quite a bit of a mess. ================================================ FILE: docs/development/input-api.md ================================================ # Libretro Input API ## Overview Libretro's input system is based on abstracted input device types which are polled via callbacks provided by the libretro API. For core developers, the value of these abstractions is that cores can be coded with an 'ideal' input type abstraction in mind while giving frontend developers and users the freedom to map that abstraction to any number of hardware or software input sources. For example, native libretro cores and source ports could be written to poll the RetroPad, the gamepad abstraction, while the frontend allows the user to map the RetroPad to their physical keyboard or mouse. This is also an advantage for emulator cores, where the input abstraction is selected to match the type or types of input available on the emulated system. For example, the libretro pointer abstraction is available for emulating input for systems like the Nintendo DS; frontends can allow the user to map a mouse or other suitable input device in addition to a hardware touchscreen. Meanwhile, on platforms like smartphones and tablets, the user can utilize their touch hardware for a more authentic emulation experience without as much code for the core to maintain. Libretro input device abstractions include: * RetroPad - Digital Gamepad or Joystick - Digital Gamepad or Joystick with Analog Controls * Mouse * Pointer * Keyboard * Lightgun ### Reference implementations The [`libretro-test` core](https://github.com/libretro/libretro-samples/tree/master/tests/test) provides a reference implementation in the C programming language for many aspects of the libretro input API. As of March 2021, `libretro-test` does not yet incorporate the latest additions to the input API, but still serves as an important resource. # Input Abstractions ## RetroPad The **RetroPad** is a controller abstraction interface defined by the Libretro API. It is the primary input device for a libretro frontend. Unless a core absolutely requires the use of a keyboard with no possible fallback for gamepad-type controls, a [[Libretro core]] should always be implemented as such that it is directly controllable by the RetroPad. ![RetroPad Conceptual Diagram](../image/guides/retropad-conceptual-diagram.png) In terms of button layout and functionality, the RetroPad is based on the original PlayStation gamepad and the Super Nintendo gamepad. ![Mega Drive 6-Button Gamepad](../image/controller/md6.png) Above: An example of the RetroPad gamepad abstraction mapped to the Megadrive 6-Button gamepad. ### Digital RetroPad `RETRO_DEVICE_JOYPAD`: A RetroPad abstraction with all digital controls can be used. The conceptual arrangement for the buttons for the RetroPad is inspired by the Super Nintendo controller and the Sony Playstation DualShock. The minimum implementation required for the digital RetroPad abstraction: * At least two shoulder buttons * At least four face buttons * At least one D-pad * A `Start` button and a `Select`/`Back` button. ### Analog RetroPad `RETRO_DEVICE_ANALOG`: An analog subtype of the RetroPad abstraction with one or more analog inputs can be used. Conceptually inspired by the Sony DualShock2, this adds two analog sticks to the digital RetroPad and allows all buttons to return analog values in the range of `[-0x7fff, 0x7fff]`, although some devices may return `-0x8000`. Positive X axis is right. Positive Y axis is down. Buttons are returned in the range `[0, 0x7fff]`. **hiddenasbestos**, author of the current revision of the analog RetroPad API, [provides a reference implementation in C](https://github.com/libretro/libretro-common/pull/50#issue-153412324) that checks for analog button values before falling back to the digital `RETRO_DEVICE_JOYPAD`. This approach supports frontends that do not implement the analog input API. ```c static uint16_t get_analog_button( retro_input_state_t input_state_cb, int player_index, int id ) { uint16_t button; // NOTE: Not all front-ends support analog buttons (or pre-date it) // so we need to handle this in a graceful way. // First, try and get an analog value using the new libretro API constant button = input_state_cb( player_index, RETRO_DEVICE_ANALOG, RETRO_DEVICE_INDEX_ANALOG_BUTTON, id ); if ( button == 0 ) { // If we got exactly zero, we're either not pressing the button, or the front-end // is not reporting analog values. We need to do a second check using the classic // digital API method, to at least get some response - better than nothing. // NOTE: If we're honestly just not holding the button, we're still going to get zero. button = input_state_cb( player_index, RETRO_DEVICE_JOYPAD, 0, id ) ? 0x7FFF : 0; } return button; } ``` ## Mouse Input `RETRO_DEVICE_MOUSE`: X and Y coordinates are reported relatively to last poll (poll callback) and it is up to the core to keep track of where the pointer coordinates with respect to the display. ## Pointer Input `RETRO_DEVICE_POINTER`: The pointer abstraction represents pen, stylus, touch and other input devices for emulated devices that use absolute coordinates with respect to the screen. Coordinates in X and Y are reported as `[-0x7fff, 0x7fff]`: `-0x7fff` corresponds to the far left/top of the screen, `0x7fff` to the far right/bottom of the screen. The "screen" is defined as area that is passed to the frontend and later displayed on the monitor. The frontend is free to scale/resize this screen as it sees fit but `(X, Y) = (-0x7fff, -0x7fff)` will always correspond to the top-left pixel of the display. ## Keyboard Input `RETRO_DEVICE_KEYBOARD`: The libretro API allows a core to poll the frontend for the raw current pressed state of keys. There is also a callback available which is called by the frontend in response to keyboard events. `down` is set if the key is being pressed and `false` if it is being released. Even though the frontend should try to synchronize keypresses with keycode events, cores should assume that multiple characters can be generated from a single keypress. In other words, keycode events should be treated separately from character events. Similarily if only a keycode event is generated with no corresponding character, the character should be `0`. ## Lightgun Input `RETRO_DEVICE_LIGHTGUN`: The libretro lightgun abstraction reports X/Y coordinates in screen space (similar to the pointer) in the range `[-0x8000, 0x7fff]` in both axes, with zero being center and `-0x8000` being out of bounds. The core an query the on/off screen state of the lightgun. It features a trigger, start/select buttons, auxiliary action buttons and a directional pad. A forced off-screen shot can be requested for auto-reloading function in some games. ================================================ FILE: docs/development/libretro-overview.md ================================================ # Libretro Development Overview The Libretro API is a lightweight C-based Application Programming Interface (API) that exposes generic audio, video, and input callbacks. ### Frontends and cores There are two sides to Libretro development: - **frontends** are programs that can run libretro-compatible cores. - **cores** are program (such as a game, emulator, or media player) that has been ported to the libretro API so that it can be executed by libretro frontends. Developers of cores such as standalone games, game emulators, media players, and other applications don’t have to worry about writing different video drivers for Direct3D, OpenGL or worrying about catering to all possible input APIs, sound APIs, gamepads, etc. Cores are built as a single library file which can be executed by any frontend that supports the libretro API. The frontend's responsibility is to provide all the implementation-specific details. The core's responsibility is solely to provide the main program. ## libretro.h The libretro API consists of several functions outlined in libretro.h, found in the RetroArch source package. The API header is compatible with C99 and C++. From C99, the bool type and `` are used. The latest version of this file can be found [in `libretro-common`](https://github.com/libretro/RetroArch/blob/master/libretro-common/include/libretro.h). ## Core development resources You can see a partial list of the cores which are maintained as part of [libretro's github repositories](http://github.com/libretro/) in the section `For Users > Core Documentation`. ### Core development overview [Visit the overview on libretro core development](./cores/developing-cores.md). ## Frontend development resources [A growing list of libretro frontends](frontends.md) is available, reflecting a variety of host systems and use cases. ### RetroArch Reference Frontend RetroArch is the libretro "reference frontend" and is available across a wide range of host platforms. Learn more about RetroARch development in the section `For Developers > RetroArch Development`. ## Libretro-powered operating systems [Lakka](http://www.lakka.tv/), based on LibreELEC, is Libretro's reference operating system distribution. Below is a partial list of external distributions that also use libretro or RetroArch as part of their backend technology: * [Batocera.linux](http://batocera.org/) * [RetroPie](http://retropie.org.uk/) * [Recalbox](http://recalbox.com/) !!! info "Licensing" Libretro is an open specification that is 100% free to implement, with no licensing fees or strings attached. Our reference frontend is RetroArch. The two projects are not the same, and this is reflected in the licensing. RetroArch is licensed via GPLv3 whereas the libretro API is a MIT-licensed API. ================================================ FILE: docs/development/licenses.md ================================================ # Licenses There is software behind RetroArch and Lakka that is protected by Non-Commercial licenses. It is important to respect the wishes of the developers and people behind the respective projects. See below for a summary of the licenses behind RetroArch and its cores: ## Non-commercial **SOFTWARE LISTED IN THE TABLE BELOW ARE PROTECTED BY NON-COMMERCIAL LICENSES. EVERY ENTRY HAS A HYPERLINK FOR PROOF OF THE SOFTWARE'S LICENSE** **SOFTWARE LISTED IN THE TABLE BELOW MAY NOT BE SOLD, NOR MAY THEY BE USED IN A COMMERCIAL PRODUCT OR ACTIVITY WITHOUT COPYRIGHT HOLDERS' APPROVAL.** | Software | License | Non-commercial | |----------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|----------------| | [Lakka](http://www.lakka.tv/) | [Non-commercial](http://www.lakka.tv/doc/FAQ/) | Non-commercial | | [Opera](../library/opera.md) | [Non-commercial](https://github.com/libretro/opera-libretro/blob/master/libopera/opera_core.h) | Non-commercial | | [AmiArcadia](../library/amiarcadia.md) | [Non-commercial](https://amigan.1emu.net/releases/) | Non-commercial | | [Cannonball](../library/cannonball.md) | [Non-commercial](https://github.com/libretro/cannonball/blob/master/docs/license.txt) | Non-commercial | | [Dinothawr](../library/dinothawr.md) | [Non-commercial](https://github.com/libretro/Dinothawr/blob/master/LICENSE) | Non-commercial | | FB Alpha | [Non-commercial](https://github.com/libretro/fbalpha/blob/master/src/license.txt) | Non-commercial | | FB Alpha 2012 | [Non-commercial](https://github.com/libretro/fbalpha2012/blob/master/docs/license.txt) | Non-commercial | | FB Alpha 2012 CPS-1 | [Non-commercial](https://github.com/libretro/fbalpha2012_cps1/blob/master/src/license.txt) | Non-commercial | | FB Alpha 2012 CPS-2 | [Non-commercial](https://github.com/libretro/fbalpha2012_cps2/blob/master/src/license.txt) | Non-commercial | | FB Alpha 2012 CPS-3 | [Non-commercial](https://github.com/libretro/fbalpha2012_cps3/blob/master/docs/license.txt) | Non-commercial | | FB Alpha 2012 Neo Geo | [Non-commercial](https://github.com/libretro/fbalpha2012_neogeo/blob/master/src/license.txt) | Non-commercial | | fMSX | [Non-commercial](https://github.com/libretro/fmsx-libretro/blob/master/LICENSE) | Non-commercial | | [Genesis Plus GX](../library/genesis_plus_gx.md) | [Non-commercial](https://github.com/libretro/Genesis-Plus-GX/blob/master/LICENSE.txt) | Non-commercial | | MAME 2000 | [MAME (Non-commercial)](https://github.com/libretro/mame2000-libretro/blob/master/readme.txt) | Non-commercial | | [MAME 2003](../library/mame_2003.md) | [MAME (Non-commercial)](https://github.com/libretro/mame2003-libretro/blob/master/LICENSE.md) | Non-commercial | | MAME 2003 Midway | [MAME (Non-commercial)](https://github.com/libretro/mame2003_midway/blob/master/docs/mame.txt) | Non-commercial | | MAME 2003-Plus | [MAME (Non-commercial)](https://github.com/libretro/mame2003-plus-libretro/blob/master/LICENSE.md) | Non-commercial | | MAME 2009 | [MAME (Non-commercial)](https://github.com/r-type/mame2009/blob/master/docs/mame.txt) | Non-commercial | | MAME 2010 | [MAME (Non-commercial)](https://github.com/libretro/mame2010-libretro/blob/master/docs/mame.txt) | Non-commercial | | MAME 2014 | [MAME (Non-commercial)](https://github.com/libretro/mame2014-libretro/blob/master/docs/license.txt) | Non-commercial | | MESS 2014 | [MAME (Non-commercial)](https://github.com/libretro/mame2014-libretro/blob/master/docs/license.txt) | Non-commercial | | [PicoDrive](../library/picodrive.md) | [MAME (Non-commercial)](https://github.com/libretro/picodrive/blob/master/COPYING) | Non-commercial | | [Snes9x](../library/snes9x.md) | [Non-commercial](https://github.com/snes9xgit/snes9x/blob/master/LICENSE) | Non-commercial | | [Snes9x 2002](../library/snes9x_2002.md) | [Non-commercial](https://github.com/libretro/snes9x/blob/master/docs/snes9x-license.txt) | Non-commercial | | [Snes9x 2005](../library/snes9x_2005.md) | [Non-commercial](https://github.com/libretro/snes9x/blob/master/docs/snes9x-license.txt) | Non-commercial | | [Snes9x 2005 Plus](../library/snes9x_2005_plus.md) | [Non-commercial](https://github.com/libretro/snes9x/blob/master/docs/snes9x-license.txt) | Non-commercial | | [Snes9x 2010](../library/snes9x_2010.md) | [Non-commercial](https://github.com/libretro/snes9x2010/blob/master/LICENSE.txt) | Non-commercial | | UME 2014 | [MAME (Non-commercial)](https://github.com/libretro/mame2014-libretro/blob/master/docs/license.txt) | Non-commercial | ## Libretro | Libretro | License | Non-commercial | |---------------------------------------------------------|--------------------------------------------------------------------|----------------| | [LibRetro API](https://www.libretro.com/index.php/api/) | [MIT](https://www.libretro.com/index.php/api/) | | | [RetroArch](http://www.retroarch.com/) | [GPLv3](https://github.com/libretro/RetroArch/blob/master/COPYING) | | | [Lakka](http://www.lakka.tv/) | [Non-commercial](http://www.lakka.tv/doc/FAQ/) | Non-commercial | | [libretro/docs](https://docs.libretro.com/) | [MIT](https://github.com/libretro/docs/blob/master/LICENSE) | | | [libretro/retroarch-assets](https://github.com/libretro/retroarch-assets) | [Attribution 4.0 International (CC BY 4.0)](https://github.com/libretro/retroarch-assets/blob/master/COPYING) | | ## Cores | Core | License | Non-commercial | |----------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|----------------| | [3D Engine](../library/3d_engine.md) | [GPLv3](https://github.com/libretro/libretro-3dengine/blob/master/license) | | | [2048](../library/2048.md) | [Public Domain](https://github.com/libretro/libretro-2048/blob/master/COPYING) | | | [Anarch](../library/anarch.md) | [CC0](https://codeberg.org/iyzsong/anarch-libretro/src/branch/master/LICENSE) | | | [Ardens](../library/ardens.md) | [MIT](https://github.com/tiberiusbrown/Ardens/blob/master/LICENSE.txt) | | | [AmiArcadia](../library/amiarcadia.md) | [Non-commercial](https://amigan.1emu.net/releases/) | Non-commercial | | [Atari800](../library/atari800.md) | [GPLv2](https://github.com/atari800/atari800/blob/master/COPYING) | | | [Beetle bsnes](../library/beetle_bsnes.md) | [GPLv2](https://github.com/libretro/beetle-bsnes-libretro/blob/master/COPYING) | | | [Beetle Cygne](../library/beetle_cygne.md) | [GPLv2](https://github.com/libretro/beetle-wswan-libretro/blob/master/COPYING) | | | [Beetle GBA](../library/beetle_gba.md) | [GPLv2](https://github.com/libretro/beetle-gba-libretro/blob/master/COPYING) | | | [Beetle Lynx](../library/beetle_lynx.md) | [zlib](https://github.com/libretro/beetle-lynx-libretro/blob/master/mednafen/lynx/license.txt), [GPLv2](https://github.com/libretro/beetle-lynx-libretro/blob/master/COPYING) | | | [Beetle NeoPop](../library/beetle_neopop.md) | [GPLv2](https://github.com/libretro/beetle-ngp-libretro/blob/master/COPYING) | | | [Beetle PC-FX](../library/beetle_pc_fx.md) | [GPLv2](https://github.com/libretro/beetle-pcfx-libretro/blob/master/COPYING) | | | [Beetle PCE FAST](../library/beetle_pce_fast.md) | [GPLv2](https://github.com/libretro/beetle-pce-fast-libretro/blob/master/COPYING) | | | [Beetle PSX](../library/beetle_psx.md) | [GPLv2](https://github.com/libretro/beetle-psx-libretro/blob/master/COPYING) | | | [Beetle PSX HW](../library/beetle_psx_hw.md) | [GPLv2](https://github.com/libretro/beetle-psx-libretro/blob/master/COPYING) | | | [Beetle Saturn](../library/beetle_saturn.md) | [GPLv2](https://github.com/libretro/beetle-saturn-libretro/blob/master/COPYING) | | | [Beetle SGX](../library/beetle_sgx.md) | [GPLv2](https://github.com/libretro/beetle-supergrafx-libretro/blob/master/COPYING) | | | [Beetle VB](../library/beetle_vb.md) | [GPLv2](https://github.com/libretro/beetle-vb-libretro/blob/master/COPYING) | | | [blueMSX](../library/bluemsx.md) | [GPLv2](https://github.com/libretro/blueMSX-libretro/blob/master/license.txt) | | | [bnes](../library/bnes.md) | [GPLv3](https://github.com/libretro/bnes-libretro/blob/master/license) | | | [bsnes-mercury Accuracy](../library/bsnes_mercury_accuracy.md) | [GPLv3](https://github.com/libretro/bsnes-mercury/blob/master/LICENSE) | | | [bsnes-mercury Balanced](../library/bsnes_mercury_balanced.md) | [GPLv3](https://github.com/libretro/bsnes-mercury/blob/master/LICENSE) | | | [bsnes-mercury Performance](../library/bsnes_mercury_performance.md) | [GPLv3](https://github.com/libretro/bsnes-mercury/blob/master/LICENSE) | | | [bsnes Accuracy](../library/bsnes_accuracy.md) | [GPLv3](https://github.com/libretro/bsnes-libretro/blob/libretro/COPYING) | | | [bsnes Balanced](../library/bsnes_balanced.md) | [GPLv3](https://github.com/libretro/bsnes-libretro/blob/libretro/COPYING) | | | [bsnes C++98 (v085)](../library/bsnes_cplusplus98.md) | [GPLv3](https://github.com/libretro/bsnes-libretro/blob/libretro/COPYING) | | | [bsnes Performance](../library/bsnes_performance.md) | [GPLv3](https://github.com/libretro/bsnes-libretro/blob/libretro/COPYING) | | | [Caprice32](../library/caprice32.md) | [GPLv2](https://github.com/ColinPitrat/caprice32/blob/master/COPYING.txt) | | | [ChaiLove](../library/chailove.md) | [MIT](https://github.com/libretro/libretro-chailove/blob/master/COPYING) | | | [Citra](../library/citra.md) | [GPLv2](https://github.com/citra-emu/citra/blob/master/license.txt) | | | [Citra Canary/Experimental](../library/citra_canary.md) | [GPLv2](https://github.com/citra-emu/citra/blob/master/license.txt) | | | [ClownMDEmu](../library/clownmdemu.md) | [AGPLv3](https://github.com/Clownacy/clownmdemu-libretro/blob/master/LICENCE.txt) | | | [Craft](../library/craft.md) | [MIT](https://github.com/libretro/Craft/blob/master/LICENSE.md) | | | [CrocoDS](../library/crocods.md) | [MIT](https://github.com/libretro/libretro-crocods/blob/master/LICENSE) | | | [DeSmuME 2015](../library/desmume_2015.md) | [GPLv2](https://github.com/libretro/desmume2015/blob/master/desmume/COPYING) | | | [DeSmuME](../library/desmume.md) | [GPLv2](https://github.com/TASVideos/desmume/blob/master/license.txt) | | | [DICE](../library/dice.md) | [GPLv3](https://github.com/mittonk/dice-libretro/blob/master/LICENSE.txt) | | | [Dinothawr](../library/dinothawr.md) | [Non-commercial](https://github.com/libretro/Dinothawr/blob/master/LICENSE) | Non-commercial | | Dolphin | [GPLv2](https://github.com/dolphin-emu/dolphin/blob/master/license.txt) | | | DOSBox | [GPLv2](https://github.com/libretro/dosbox-libretro/blob/master/COPYING) | | | DOSBox Pure | [GPLv2](https://github.com/libretro/dosbox-libretro/blob/master/COPYING) | | | [doukutsu-rs](../library/doukutsu-rs.md) | [MIT](https://github.com/DrGlaucous/doukutsu-rs-nm/blob/retroarch-dev/LICENSE) | | | Dummy Core | [MIT](https://github.com/libretro/libretro-samples/blob/master/license) | | | Dungeon Crawl Stone Soup | [GPLv2+](https://github.com/libretro/crawl-ref/blob/master/crawl-ref/licence.txt) | | | EasyRPG | [GPLv3](https://github.com/libretro/easyrpg-libretro/blob/master/COPYING) | | | [EightyOne](../library/eightyone.md) | [GPLv3](https://github.com/libretro/81-libretro/blob/master/LICENSE) | | | [Elektronika - BK-0010/BK-0011](../library/bk.md) | [BSD](https://github.com/libretro/bk-emulator/blob/master/COPYING) | | | [EmuSCV](../library/emuscv.md) | [GPLv2](https://github.com/libretro/) | | | [Emux CHIP-8](../library/emux_chip8.md) | [GPLv2](https://github.com/libretro/emux/blob/master/COPYING) | | | [Emux GB](../library/emux_gb.md) | [GPLv2](https://github.com/libretro/emux/blob/master/COPYING) | | | [Emux NES](../library/emux_nes.md) | [GPLv2](https://github.com/libretro/emux/blob/master/COPYING) | | | [Emux SMS](../library/emux_sms.md) | [GPLv2](https://github.com/libretro/emux/blob/master/COPYING) | | | [ep128emu](../library/ep128emu.md) | [GPLv2](https://github.com/libretro/ep128emu-core/blob/master/COPYING) | | | FB Alpha | [Non-commercial](https://github.com/libretro/fbalpha/blob/master/src/license.txt) | Non-commercial | | FB Alpha 2012 | [Non-commercial](https://github.com/libretro/fbalpha2012/blob/master/docs/license.txt) | Non-commercial | | FB Alpha 2012 CPS-1 | [Non-commercial](https://github.com/libretro/fbalpha2012_cps1/blob/master/src/license.txt) | Non-commercial | | FB Alpha 2012 CPS-2 | [Non-commercial](https://github.com/libretro/fbalpha2012_cps2/blob/master/src/license.txt) | Non-commercial | | FB Alpha 2012 CPS-3 | [Non-commercial](https://github.com/libretro/fbalpha2012_cps3/blob/master/docs/license.txt) | Non-commercial | | FB Alpha 2012 Neo Geo | [Non-commercial](https://github.com/libretro/fbalpha2012_neogeo/blob/master/src/license.txt) | Non-commercial | | [FCEUmm](../library/fceumm.md) | [GPLv2](https://github.com/libretro/libretro-fceumm/blob/master/Copying) | | | [FFmpeg](../library/ffmpeg.md) | [LGPLv2, GPLv2](https://github.com/libretro/FFmpeg/blob/master/LICENSE.md) | | | [Flycast](../library/flycast.md) | [GPLv2](https://github.com/libretro/flycast/blob/master/LICENSE) | | | fMSX | [Non-commercial](https://github.com/libretro/fmsx-libretro/blob/master/LICENSE) | Non-commercial | | FreeIntv | [GPLv3](https://github.com/libretro/FreeIntv/blob/master/LICENSE) | | | FreeJ2ME | [GPLv3](https://github.com/hex007/freej2me/blob/master/LICENSE) | | | Frodo | [GPLv2](https://github.com/r-type/frodo-libretro/blob/master/COPYING) | | | Fuse | [GPLv3](https://github.com/libretro/fuse-libretro/blob/master/LICENSE) | | | [GAM4980](../library/gam4980.md) | [GPLv3](https://codeberg.org/iyzsong/gam4980/raw/branch/master/COPYING) | | | [Gambatte](../library/gambatte.md) | [GPLv2](https://github.com/libretro/gambatte-libretro/blob/master/COPYING) | | | [Game Music Emu](../library/game_music_emu.md) | [GPLv3](https://github.com/libretro/libretro-gme/blob/master/LICENSE) | | | [Gearboy](../library/gearboy.md) | [GPLv3](https://github.com/drhelius/Gearboy/blob/master/LICENSE) | | | [Gearcoleco](../library/gearcoleco.md) | [GPLv3](https://github.com/drhelius/Gearcoleco/blob/master/LICENSE) | | | [Geargrafx](../library/geargrafx.md) | [GPLv3](https://github.com/drhelius/Geargrafx/blob/master/LICENSE) | | | [Gearlynx](../library/gearlynx.md) | [GPLv3](https://github.com/drhelius/Gearlynx/blob/master/LICENSE) | | | [Gearsystem](../library/gearsystem.md) | [GPLv3](https://github.com/drhelius/Gearsystem/blob/master/LICENSE) | | | [Genesis Plus GX](../library/genesis_plus_gx.md) | [Non-commercial](https://github.com/libretro/Genesis-Plus-GX/blob/master/LICENSE.txt) | Non-commercial | | [Geolith](../library/geolith.md) | [BSD-3-Clause, MIT](https://github.com/libretro/geolith-libretro/blob/master/LICENSE) | | | [gpSP](../library/gpsp.md) | [GPLv2](https://github.com/libretro/gpsp/blob/master/COPYING) | | | [GW](../library/gw.md) | [zlib](https://github.com/libretro/gw-libretro/blob/master/LICENSE) | | | [Handy](../library/handy.md) | [zlib](https://github.com/libretro/libretro-handy/blob/master/lynx/license.txt) | | | [Holani](../library/holani.md) | [GPLv3](https://github.com/LLeny/holani-retro/blob/main/LICENSE) | | | [Hatari](../library/hatari.md) | [GPLv2](https://github.com/libretro/hatari/blob/master/readme.txt) | | | [higan Accuracy](../library/higan_accuracy.md) | [GPLv3](https://gitlab.com/higan/higan/blob/master/LICENSE.txt) | | | [Imageviewer](../library/imageviewer.md) | [MIT](https://github.com/libretro/RetroArch/blob/master/cores/libretro-imageviewer/LICENSE) | | | [JollyCV](../library/jollycv.md) | [BSD-3-Clause, MIT](https://github.com/libretro/jollycv/blob/master/LICENSE) | | | [Kronos](../library/kronos.md) | [GPLv2](https://github.com/libretro/yabause/blob/kronos/yabause/COPYING) | | | [LowRES NX](../library/lowres_nx.md) | [zlib](https://github.com/timoinutilis/lowres-nx/blob/master/LICENSE) | | | [Lutro](../library/lutro.md) | [MIT](https://github.com/libretro/libretro-lutro/blob/master/LICENSE) | | | M2000 | [GPLv3](https://github.com/p2000t/M2000/blob/main/LICENSEE) | | | MAME | [BSD-3-Clause & GNU GPLv2](http://mamedev.org/legal.html) | | | MAME 2000 | [MAME (Non-commercial)](https://github.com/libretro/mame2000-libretro/blob/master/readme.txt) | Non-commercial | | [MAME 2003](../library/mame_2003.md) | [MAME (Non-commercial)](https://github.com/libretro/mame2003-libretro/blob/master/LICENSE.md) | Non-commercial | | MAME 2003 Midway | [MAME (Non-commercial)](https://github.com/libretro/mame2003_midway/blob/master/docs/mame.txt) | Non-commercial | | MAME 2003-Plus | [MAME (Non-commercial)](https://github.com/libretro/mame2003-plus-libretro/blob/master/LICENSE.md) | Non-commercial | | MAME 2009 | [MAME (Non-commercial)](https://github.com/r-type/mame2009/blob/master/docs/mame.txt) | Non-commercial | | MAME 2010 | [MAME (Non-commercial)](https://github.com/libretro/mame2010-libretro/blob/master/docs/mame.txt) | Non-commercial | | MAME 2014 | [MAME (Non-commercial)](https://github.com/libretro/mame2014-libretro/blob/master/docs/license.txt) | Non-commercial | | MAME 2016 | [BSD-3-Clause & GNU GPLv2](http://mamedev.org/legal.html) | | | [melonDS 2021](../library/melonds.md) | [GPLv3](https://github.com/libretro/melonDS/blob/master/LICENSE) | | | [melonDS DS](../library/melonds_ds.md) | [GPLv3](https://github.com/JesseTG/melonds-ds/blob/main/LICENSE) | | | [Mesen](../library/mesen.md) | [GPLv3](https://github.com/SourMesen/Mesen/blob/master/README.md) | | | [Mesen-S](../library/mesen-s.md) | [GPLv3](https://github.com/SourMesen/Mesen-S/blob/master/README.md) | | | MESS 2014 | [MAME (Non-commercial)](https://github.com/libretro/mame2014-libretro/blob/master/docs/license.txt) | Non-commercial | | [Meteor](../library/meteor.md) | [GPLv3](https://github.com/libretro/meteor-libretro/blob/master/COPYING) | | | [mGBA](../library/mgba.md) | [MPLv2.0](https://github.com/libretro/mgba/blob/master/LICENSE) | | | [MicroW8](../library/microw8.md) | [Unlicense](https://github.com/libretro/uw8-libretro/blob/main/UNLICENSE) | | | [mkxp-z](../library/mkxp-z.md) | [GPLv2](https://github.com/mkxp-z/mkxp-z/blob/dev/COPYING) | | | mpv | [GPLv3](https://github.com/libretro/libretro-mpv/blob/master/LICENSE) | | | [Mr.Boom](../library/mr_boom.md) | [MIT](https://github.com/libretro/mrboom-libretro/blob/master/LICENSE) | | | Mupen64Plus | [GPLv3](https://github.com/libretro/mupen64plus-libretro/blob/master/LICENSE) | | | Mupen64Plus GLES3 | [GPLv3](https://github.com/libretro/mupen64plus-libretro/blob/master/LICENSE) | | | Neko Project II | | | | Neko Project II Kai | [MIT](https://github.com/AZO234/NP2kai/blob/master/LICENSE) | | | [Nestopia](../library/nestopia.md) | [GPLv2](https://github.com/libretro/nestopia/blob/master/COPYING) | | | [Numero](../library/numero.md) | [GPLv2](https://github.com/nbarkhina/numero/blob/master/LICENSE) | | | nSide Balanced | [GPLv3](https://github.com/hex-usr/nSide/blob/master/gpl-3.0.txt) | | | [NXEngine](../library/nxengine.md) | [GPLv3](https://github.com/gameblabla/nxengine-nspire/blob/master/LICENSE) | | | O2EM | [Artistic License](https://sourceforge.net/projects/o2em/) | | | [OpenLara](../library/openlara.md) | [BSD-2-Clause](https://github.com/XProger/OpenLara/blob/master/LICENSE) | | | [Opera](../library/opera.md) | [Non-commercial](https://github.com/libretro/opera-libretro/blob/master/libopera/opera_core.h) | | | P-UAE | [GPLv2](https://github.com/libretro/PUAE/blob/master/COPYING) | | | ParaLLEl N64 | [GPLv3](https://github.com/libretro/mupen64plus-libretro/blob/master/LICENSE) | | | PCem | [GPLv2](https://github.com/libretro/libretro-pcem/blob/master/COPYING) | | | [PCSX ReARMed](../library/pcsx_rearmed.md) | [GPLv2](https://github.com/libretro/pcsx_rearmed/blob/master/COPYING) | | | PCSX ReARMed [Interpreter] | [GPLv2](https://github.com/libretro/pcsx_rearmed/blob/master/COPYING) | | | [PD777](../library/pd777.md) | [MIT](https://github.com/mittonk/PD777/blob/main/LICENSE) | | | [PicoDrive](../library/picodrive.md) | [MAME (Non-commercial)](https://github.com/libretro/picodrive/blob/master/COPYING) | Non-commercial | | [PocketCDG](../library/pocketcdg.md) | [MIT](https://github.com/libretro/libretro-pocketcdg/blob/master/LICENSE) | | | [PokeMini](../library/pokemini.md) | [GPLv3](https://github.com/libretro/PokeMini/blob/master/LICENSE) | | | [PPSSPP](../library/ppsspp.md) | [GPLv2](https://github.com/hrydgard/ppsspp/blob/master/LICENSE.TXT) | | | [PrBoom](../library/prboom.md) | [GPLv2](https://github.com/libretro/libretro-prboom/blob/master/COPYING) | | | [ProSystem](..//library/prosystem.md) | [GPLv2](https://github.com/libretro/prosystem-libretro/blob/master/License.txt) | | | PX68k | [kero_src.txt](https://github.com/libretro/px68k-libretro/blob/master/doc/kero_src.txt) | | | | | [QuickNES](../library/quicknes.md) | [GPLv2](https://github.com/kode54/QuickNES/blob/master/COPYING) | | | [Redream (libretro fork)](../library/redream.md) | [GPLv3](https://github.com/libretro/redream/blob/master/LICENSE.txt) | | | [REminiscence](../library/reminiscence.md) | GPLv3 | | | RemoteJoy | [GPLv2](https://github.com/libretro/libretro-remotejoy/blob/master/LICENSE) | | | Remote RetroPad | [MIT](https://github.com/libretro/libretro-samples/blob/master/license) | | | [RVVM](../library/rvvm.md) | [GPLv3](https://github.com/LekKit/RVVM/blob/staging/LICENSE-GPL), [MPLv2.0](https://github.com/LekKit/RVVM/blob/staging/LICENSE-MPL) | | | [SameBoy](../library/sameboy.md) | [MIT](https://github.com/libretro/SameBoy/blob/master/LICENSE) | | | [SameDuck](../library/sameduck.md) | [MIT](https://github.com/libretro/) | | | [SAME_CDI](../library/same_cdi.md) | [GPLv2](https://github.com/libretro/same_cdi/blob/master/COPYING) | | | [ScummVM](../library/scummvm.md) | [GPLv2](https://github.com/libretro/scummvm/blob/master/COPYING) | | | [Snes9x](../library/snes9x.md) | [Non-commercial](https://github.com/libretro/snes9x/blob/master/docs/snes9x-license.txt) | Non-commercial | | [Snes9x 2002](../library/snes9x_2002.md) | [Non-commercial](https://github.com/libretro/snes9x/blob/master/docs/snes9x-license.txt) | Non-commercial | | [Snes9x 2005](../library/snes9x_2005.md) | [Non-commercial](https://github.com/libretro/snes9x/blob/master/docs/snes9x-license.txt) | Non-commercial | | [Snes9x 2005 Plus](../library/snes9x_2005_plus.md) | [Non-commercial](https://github.com/libretro/snes9x/blob/master/docs/snes9x-license.txt) | Non-commercial | | [Snes9x 2010](../library/snes9x_2010.md) | [Non-commercial](https://github.com/libretro/snes9x2010/blob/master/LICENSE.txt) | Non-commercial | | [Stella](../library/stella.md) | [GPLv2](https://github.com/stella-emu/stella/blob/master/License.txt) | | | TempGBA | [GPLv2](https://github.com/libretro/TempGBA-libretro/blob/master/copyright) | | | [TGB Dual](../library/tgb_dual.md) | [GPLv2](https://github.com/libretro/tgbdual-libretro/blob/master/docs/COPYING-2.0.txt) | | | [The Powder Toy](../library/the_powder_toy.md) | [GPLv3](https://github.com/libretro/ThePowderToy/blob/master/LICENSE) | | | [Theodore](../library/theodore.md) | [GPLv3](https://github.com/Zlika/theodore/blob/master/LICENSE) | | | [TyrQuake](../library/tyrquake.md) | [GPLv2](https://github.com/libretro/tyrquake/blob/master/gnu.txt) | | | UME 2014 | [MAME (Non-commercial)](https://github.com/libretro/mame2014-libretro/blob/master/docs/license.txt) | Non-commercial | | [Uzem](../library/uzem.md) | [GPLv3](https://github.com/Uzebox/uzebox/blob/master/gpl-3.0.txt) | | | [VaporSpec](../library/vaporspec.md) | [MIT](https://github.com/minkcv/vm/blob/master/LICENSE.md) | [VBA-M](../library/vba_m.md) | [GPLv2](https://github.com/libretro/vbam-libretro/blob/master/doc/gpl.txt) | | | [VBA Next](../library/vba_next.md) | [GPLv2](https://github.com/libretro/vba-next/blob/master/LICENSE) | | | [vecx](../library/vecx.md) | [GPLv3](https://github.com/libretro/libretro-vecx/blob/master/LICENSE.md) | | | [VeMUlator](../library/vemulator.md) | [GPLv3](https://github.com/MJaoune/vemulator-libretro/blob/master/COPYING) | | | VICE C64 | [GPLv2](https://github.com/r-type/vice3.0-libretro/blob/master/vice/COPYING) | | | VICE C128 | [GPLv2](https://github.com/r-type/vice3.0-libretro/blob/master/vice/COPYING) | | | VICE PLUS4 | [GPLv2](https://github.com/r-type/vice3.0-libretro/blob/master/vice/COPYING) | | | VICE VIC20 | [GPLv2](https://github.com/r-type/vice3.0-libretro/blob/master/vice/COPYING) | | | Video Processor | [BSD-2-Clause](https://github.com/jaredmcneill/libretro-v4l2/blob/master/LICENSE) | | | [Vircon32](../library/vircon32.md) | [BSD-3-Clause](https://github.com/vircon32/vircon32-libretro/blob/main/LICENSE.md) | | | [Virtual Jaguar](../library/virtual_jaguar.md) | [GPLv3](https://github.com/libretro/virtualjaguar-libretro/blob/master/docs/GPLv3) | | | [VirtualXT](../library/virtualxt.md) | [zlib](https://github.com/andreas-jonsson/virtualxt/blob/develop/LICENSE) | | | [XRick](../library/xrick.md) | [GPLv3](https://github.com/libretro/xrick-libretro/blob/master/README) | | | [YabaSanshiro](../library/yabasanshiro.md) | [GPLv2](https://github.com/libretro/yabasanshiro/blob/master/yabause/COPYING) | | | [Yabause](../library/yabause.md) | [GPLv2](https://github.com/libretro/yabause/blob/master/yabause/COPYING) | | ================================================ FILE: docs/development/retroarch/compilation/3ds.md ================================================ # Nintendo 3DS Compilation / Development Guide ## Environment configuration You need the homebrew Nintendo 3DS SDK libctru and DevkitARM toolchain installed. If you are running windows you will need to install [MSYS2](http://www.msys2.org/) and point it to your devkitARM installation like this: Put these lines in RetroArch3DSEnv.sh export DEVKITPRO="/c/devkitPro" export DEVKITARM="$DEVKITPRO/devkitARM" export CTRULIB="$DEVKITPRO/libctru" export CTRBANNERTOOL="/c/Users/Emily/Desktop/RetroArchDev/CompatFiles/bannertool.exe" bash The custom bannertool is needed if you want to compile .cia builds due to a broken wav encoder in the windows version of bannertool included with RetroArch. Before building RetroArch you will have to load MSYS2 and launch `RetroArch3DSEnv.sh`, then proceed as you would for linux. The working bannertool can be compiled from the sources [here](https://github.com/Steveice10/bannertool) using MSYS2. ## RetroArch Compilation ### Fetching RetroArch Clone RetroArch's repository from [GitHub](https://github.com/libretro/RetroArch) git clone https://github.com/libretro/RetroArch.git retroarch cd retroarch For subsequent builds you only need to pull the changes from the repo cd retroarch git pull To update your local copy from the repository run git pull ### Building RetroArch separately First, you need to compile [Salamander](../glossary.md#salamander). To compile Salamander (for 3DS) run: make -f Makefile.ctr.salamander Second, to compile RetroArch (for 3DS) run: make -f Makefile.ctr !!! Note RetroArch on 3DS is statically linked. With statically linked RetroArch, each executable is a separate libretro core instead of the core being separately loaded from a single executable. A pre-existing libretro library needs to be present in the root directory in order to link RetroArch 3DS. This file needs to be called 'libretro_ctr.a'. After a few seconds/minutes you should be able to find a retroarch_ctr.elf and retroarch_ctr.dol file under that directory. ### Building RetroArch in bulk Instead of building each core one by one, you can build all cores as a batch task. Run from the main 'retroarch' directory: cd dist-scripts !!! Note Make sure that all the libretro cores that you want to compile are inside the 'dist-scripts' directory. Once inside this directory, run : ./dist-cores.sh ctr This process will also automate the packaging process for you. ### Packaging RetroArch ### Additional Tips: ## Core Compilation ### Fetching Cores The easiest way to fetch all the cores is to use libretro-super. Run ./libretro-fetch.sh ### Building Cores The easiest way to build all the cores (for 3DS) is to use libretro-super. Run ./libretro-build-ctr.sh In case you only want to build one and/or more cores instead of all, you can specify the cores you want to build after the first command in no particular order. E.g.: ./libretro-build-ctr.sh snes9x2010 fceumm Once finished, you can find the libretro cores inside directory `dist/ctr`. ================================================ FILE: docs/development/retroarch/compilation/android.md ================================================ # Compiling for Android ## Compiling from Windows You need a complete Android development environment, including the **Android SDK** and **Android NDK**. **Other dependencies:** * Cygwin (base settings for Bash scripts) * Git ### Installing OpenJDK or Oracle JDK ### Installing cygwin Download the setup tool from the official webpage and install the base distribution. ### Installing git You can install Windows git or add the cygwin git version from the cygwin installer. ### Next step: From here, follow the instructions for compiling Android from Linux. ## Compiling from Linux You need a complete android development environment ready to develop native apps. That means you have: * [Android SDK](http://developer.android.com/sdk/index.html) * [Android NDK](https://developer.android.com/tools/sdk/ndk/index.html) Use Google to figure out how to install that and make sure the appropriate executables from the above are in your path variable. These instructions have been tested under Linux (Fedora 20 and Ubuntu 18.04). They may also work in windows with cygwin. ### Getting the code git clone https://github.com/libretro/libretro-super.git cd libretro-super ./libretro-fetch.sh `./libretro-fetch.sh` can fail on `fork()` calls, repeat until all are up to date. For `./libretro-build-android-mk.sh`, some cores may fail to compile (g++ "Argument list too long" error). ### Building the cores For the core building portion of this tutorial, you'll need to put at least your NDK dir in the PATH variable for the build script to work. Just for the heck of it, I also like to throw in the tools folder from SDK as well as the build-tools (adjust to your situation): export PATH=/home/boo/Android/Sdk/ndk-bundle/build:/home/boo/Android/Sdk/tools:/home/boo/Android/Sdk/build-tools/28.0.3:$PATH ### Run build script ( read notes below before running the script): NOCLEAN=1 ./libretro-build-android-mk.sh You can omit `NOCLEAN=1` if you'd like to perform make clean on every core's repo before building each. For a variety of reasons, some of the cores may not be compiled by the script. These reasons can range from: core folder doesn't have a libretro/jni folder setup yet, core's libretro/jni folder is in a place that the script does not expect, core has been recently added to project and has not yet been added to script or you're missing some essential dependencies and the build script failed. Some cores (like snes9x2002) need an older NDK. Some core don't use jni but use make or cmake instead. In the event you are missing a core that you want, you can build it in most cases by going to its subfolder (libretro-corename) and performing this series of commands: #for example cd libretro-flycast #get corename for later corename=$(echo ${PWD##*/}|cut -d "-" -f 2) #now try to find the libretro/jni folder cd $(find . -iname "jni" -type d | grep --color=NEVER "libretro/jni") #if it exists and you don't get an error, build the core: ndk-build #if it succeeds, do this to copy built .so files to dist folder: for arch in "arm64-v8a" "armeabi-v7a" "x86" "x86_64"; do if [ -f "$arch/libretro.so" ]; then cp -v $arch/libretro.so $SRC/dist/android/$arch/"$corename"_libretro_android.so; else echo "$arch" build HAS FAILED!; fi; done You may also want to check this repo for a list of dependencies needed to build the cores: https://github.com/libretro/libretro-deps/ #these deps can usually be installed via apt-get install (don't forget to append -dev at the end). for example: sudo apt-get install libfaac-dev more info about core building can be had here: https://github.com/thebunnyrules/docs/blob/master/docs/development/cores/developing-cores.md ### Building RetroArch ### PREP WORK The RetroArch repo is fetched into the libretro-super folder by `./libretro-fetch.sh` above. You first need to fetch the submodules for it. cd retroarch git submodule update --init Now go to the project folder: cd pkg/android/phoenix Within this folder, edit `local.properties` to point to the location of your sdk and ndk directories by adding lines that look like this: ndk.dir=/complete/path/to/android-ndk-r20 sdk.dir=/complete/path/to/Sdk Eg. if you have Android Studio, your dirs should be in : ndk.dir=/home/yourUSERNAME/Android/Sdk/ndk-bundle sdk.dir=/home/yourUSERNAME/Android/Sdk If you want to build a release apk (aka an apk with none of the debug layers), you'll have to self sign it. Make a file called `keystore.properties` with the following content: storePassword=YOURPASS keyPassword=YOURPASS keyAlias=KEY_ALIAS storeFile=/full/path/to/keystore-file_NO_RELATIVE_PATHS.jks Next, generate a keystore file and be sure to put it where `keystore.properties` says it is: keytool -genkey -alias KEY_ALIS -keyalg RSA -keypass YOURPASS -keystore keystore-file.jks Now all the generated release apk will be automatically signed by gradle. Next, copy the cores, assets and overlays to an assets folder you create here: mkdir -p assets/cores mkdir assets/overlays cp ../../../../dist/android/arm64-v8a/* assets/cores/ #replace arm64-v8a here by the archetecture of the device you will be using. Google your phone's specs. cp -r ../../../../dist/info/ assets/ cp -r ../../../../retroarch/media/overlays/* assets/overlays/ Optionally, you may want to include the assets for the front-end (menu icons, fonts, images etc), shader caches, dbs, cheats, etc... These assets can be downloaded at any time during run time via the updater but if you want to bundle them into the build you may do so by downloading bundle.zip / cheats.zip and extracting them to assets folder: wget https://buildbot.libretro.com/assets/frontend/bundle.zip unzip -n bundle.zip -d assets wget https://buildbot.libretro.com/assets/frontend/cheats.zip mkdir assets/cheats unzip cheats.zip -d assets/cheats *NOTE ABOUT BUNDLED ASSETS AND CORES* I've sometimes noticed a bug where the built apk does not unpack the bundled assets and cores on first install. My workaround was to re-install the apk a second time. On the second install, the assets and cores get unpacked. This is a bug in 1.7.7 and 1.7.8. ### BUILD Now run gradlew and let it configure and sync itself and download all it's dependencies: ./gradlew Optionally: You can get a list of available tasks by doing: ./gradlew tasks Now, if all went smoothly with config step, you can proceed to build the apk #Builds release variants: Normal, ra32 and aarch64 ./gradlew assembleRelease #Build debug variants: ./gradlew assembleDebug #Builds all variants ./gradlew buildNeeded If all goes well, this will spit out an .apk. For example `build/outputs/apk/normal/debug/phoenix-normal-debug.apk`. Put it on your device with adb install -r build/outputs/apk/normal/debug/phoenix-normal-debug.apk You can find all the apks built by gradle with this command (execute from the same dir as gradlew)" find . -iname "*.apk" This should give you a list of all the outputted apks. ================================================ FILE: docs/development/retroarch/compilation/dos.md ================================================ # DOS Compilation / Development Guide ## Environment configuration This guide will use cross-compilation from Linux to build a DOS executable with the [DJGPP](http://www.delorie.com/djgpp/) toolchain. Most Linux distributions do not include this toolchain, but prebuilt binaries can be obtained [here](https://github.com/andrewwutw/build-djgpp/releases), or if you are using Arch Linux, you can use the AUR package [djgpp-gcc](https://aur.archlinux.org/packages/djgpp-gcc/) to build it easily. DJGPP builds 32-bit programs, which means an 80386 or higher processor is required. 80286 is not supported. ## Core Support !!! Note RetroArch on DOS is statically linked. With statically linked RetroArch, each executable is a separate libretro core instead of the core being separately loaded from a single executable. A pre-existing libretro library needs to be present in the root of the source directory in order to link RetroArch DOS. This file needs to be called 'libretro.a'. ## RetroArch Compilation ### Fetching RetroArch Clone RetroArch's repository from [GitHub](https://github.com/libretro/RetroArch) git clone https://github.com/libretro/RetroArch.git retroarch cd retroarch For subsequent builds you only need to pull the changes from the repo cd retroarch git pull ### Building RetroArch To compile RetroArch run the following commands inside RetroArch's source tree: CROSS_COMPILE=i686-pc-msdosdjgpp- ./configure --with-libretro="-L. -lretro" make clean make -j4 Replace the value of `CROSS_COMPILE` with the prefix of your specific toolchain if necessary. Once finished, you should find `retroarch.exe` in the current directory, this is the final binary you can run inside DOS. Since older DOS versions do not support long filenames, you may want to rename this file to something shorter. RetroArch for DOS also requires the CWSDPMI server application from the DJGPP distribution, which can be downloaded separately [here](http://www.delorie.com/pub/djgpp/current/v2misc/csdpmi7b.zip). On the target system, CWSDPMI.EXE will need to be placed in the same directory as your RetroArch executable for it to run properly. Once you have the DPMI program in place, simply run your RetroArch executable and the DPMI server will be loaded automatically at startup. It is also possible to include the DPMI server inside the main RetroArch executable so that only a single file is needed, but that is outside the scope of this document. See [here](http://www.delorie.com/djgpp/doc/utils/utils_16.html) for more information. ================================================ FILE: docs/development/retroarch/compilation/gamecube.md ================================================ # Nintendo GameCube Compilation / Development Guide ## Environment configuration You need the homebrew Nintendo GameCube SDK libogc and Devkitpro PPC toolchain installed. ## RetroArch Compilation ### Fetching RetroArch Clone RetroArch's repository from [GitHub](https://github.com/libretro/RetroArch) git clone https://github.com/libretro/RetroArch.git retroarch cd retroarch For subsequent builds you only need to pull the changes from the repo cd retroarch git pull To update your local copy from the repository run git pull ### Building RetroArch separately First, to compile RetroArch (for GameCube) run: make -f Makefile.griffin platform=ngc !!! Note RetroArch on GameCube is statically linked. With statically linked RetroArch, each executable is a separate libretro core instead of the core being separately loaded from a single executable. A pre-existing libretro library needs to be present in the root directory in order to link RetroArch GameCube. This file needs to be called 'libretro_ngc.a'. After a few seconds/minutes you should be able to find a retroarch_ngc.elf and retroarch_ngc.dol file under that directory. ### Building RetroArch in bulk Instead of building each core one by one, you can build all cores as a batch task. Run from the main 'retroarch' directory: cd dist-scripts !!! Note Make sure that all the libretro cores that you want to compile are inside the 'dist-scripts' directory. Once inside this directory, run : ./dist-cores.sh ngc This process will also automate the packaging process for you. ### Packaging RetroArch ### Additional Tips: ## Core Compilation ### Fetching Cores The easiest way to fetch all the cores is to use libretro-super. Run ./libretro-fetch.sh ### Building Cores The easiest way to build all the cores (for GameCube) is to use libretro-super. Run ./libretro-build-ngc.sh In case you only want to build one and/or more cores instead of all, you can specify the cores you want to build after the first command in no particular order. E.g.: ./libretro-build-ngc.sh snes9x2010 fceumm Once finished, you can find the libretro cores inside directory `dist/ngc`. ================================================ FILE: docs/development/retroarch/compilation/haiku.md ================================================ # Haiku Compilation / Development Guide This compilation guide will teach you how to build RetroArch for Haiku. It is more than recommended to keep your Haiku system up to date and use Nightlybuilds with upgraded packages. This video covers a quick demonstration of these subjects; 1. Environment Configuration 2. Building RetroArch Be sure to read instructions that are given on this page. ## Environment configuration The following software needs to be installed: - Haiku standard development packages (haiku_devel) - SDL libraries and development packages (libsdl_devel / libsdl2_devel) - X11 libraries and development packages (libx11_devel, libxau_devel, libxext_devel) - Mesa libraries and development packages (mesa_devel, glu_devel) - Jpeg, PNG, Zlib libraries and development packages (jpeg_devel, libpng16_devel, zlib_devel) Optional dependencies: - libxml2_devel - For XML shaders and cheat support. - freetype_devel - TTF font rendering - ffmpeg_devel - FFmpeg recording ## RetroArch Compilation ### Fetching RetroArch Clone RetroArch's repository from [GitHub](https://github.com/libretro/RetroArch) git clone https://github.com/libretro/RetroArch.git retroarch cd retroarch For subsequent builds you only need to pull the changes from the repo cd retroarch git pull To update your local copy from the repository run git pull ### Building RetroArch Make sure gcc is installed, then run: # Build ./configure --prefix=~/config/non-packaged/ --datarootdir=~/config/non-packaged/data/ --with-man_dir=~/config/non-packaged/documentation/man/ make # Install make install # Run retroarch ## Core Compilation ### Fetching Cores The easiest way to fetch all the cores is to use libretro-super. Run ./libretro-fetch.sh ### Building Cores The easiest way to build all the cores is to use libretro-super. To build all cores for Haiku, run ./libretro-build.sh In case you only want to build one and/or more cores instead of all, you can specify the cores you want to build after the first command in no particular order. E.g.: ./libretro-build.sh snes9x2010 fceumm Once finished, you can find the libretro cores inside directory `dist/haiku`. ================================================ FILE: docs/development/retroarch/compilation/ios.md ================================================ # iOS Compilation / Development Guide The following is a non-developer guide to install RetroArch on non-jailbroken iOS or tvOS devices. The minimum version of iOS supported is iOS 6.0. However, older versions have fewer features and worse core support. Additionally, building for old versions of iOS requires [old versions of Xcode](https://developer.apple.com/support/xcode/), which require old versions of macOS, all of which may be hard to come by. !!! note If you just want to sideload from an IPA file, then you can find a working build (version {{ unit.stable }}) [here for tvOS](http://buildbot.libretro.com/stable/{{ unit.stable }}/apple/tvos-arm64/RetroArchTV.ipa) and [here for iOS](http://buildbot.libretro.com/stable/{{ unit.stable }}/apple/ios-arm64/RetroArch.ipa). Instructions for installing the IPA are [here](../../..//guides/install-ios.md). Because iOS requires that all code be signed, iOS does not support installing/updating cores at runtime. Instead, all cores must be built and added to the RetroArch source tree before building RetroArch. ## Environment configuration ### Xcode The only requirement for building is Xcode, which is only available for macOS. You can get Xcode from the App Store. If you have never used Xcode before, you will need to open the Xcode preferences, and in Accounts, log in with your Apple ID. #### Sign in with your Apple ID - Open Xcode Preferences (Xcode -> Preferences) - Click the "Accounts" tab - Hit the "+" at the bottom left and choose "Apple ID" and sign in with your Apple ID - Once you’ve successfully logged in, a new team called "(Your Name) Personal Team" with the role "User" will appear beneath your Apple ID. #### Pair Xcode with your iOS or tvOS Device Connect your iPhone to your computer. For AppleTV, because you cannot connect it directly, follow the [instructions in this Apple support article](https://support.apple.com/en-gb/HT208088) to pair your device in Xcode. When finished, you should see your specific device when you go, in Xcode, to Windows -> Devices & Simulators. ### retroarch-apple-deps (optional but recommended) RetroArch optionally will automatically link with supporting libraries (including MoltenVK) that are provided by the retroarch-apple-deps repo. By default Xcode will look for these dependencies in `/usr/local/share/retroarch-apple-deps`. To get retroarch-apple-deps, run: ```shell git clone https://github.com/warmenhoven/retroarch-apple-deps.git retroarch-apple-deps sudo ln -s $PWD/retroarch-apple-deps /usr/local/share ``` ## Fetching the code ### libretro-super The easiest way to fetch the source code for RetroArch and all the cores is to use libretro-super. Open Terminal (it's in `/Applications/Utilities`) and run the following commands: ```shell git clone https://github.com/libretro/libretro-super.git libretro-super cd libretro-super ``` You can run the following command to download the source for RetroArch as well as all of the cores: ```shell ./libretro-fetch.sh ``` Or you can run the following command to download the source for RetroArch only: ```shell ./libretro-fetch.sh --retroarch ``` Or specify just the cores that you want: ```shell ./libretro-fetch.sh snes9x2010 fceumm ``` ### RetroArch repo If you choose not to use libretro-super, you can clone RetroArch's repository from [GitHub](https://github.com/libretro/RetroArch) ```shell git clone https://github.com/libretro/RetroArch.git retroarch cd retroarch ``` For subsequent builds you only need to pull the changes from the repo ```shell cd retroarch git pull ``` To update your local copy from the repository run `git pull`. ## Cores Emulator cores are needed to use RetroArch as they contain the code that drives the emulation of the system of the game you want to play. All of the cores should have the extension `.dylib` and be placed in the RetroArch source tree in the directory `pkg/apple/iOS/modules` (`pkg/apple/tvOS/modules` for tvOS). ### Downloading Pre-Built Cores Pre-built cores are available from the buildbot [for iOS here](https://buildbot.libretro.com/nightly/apple/ios-arm64/latest/) and [for tvOS here](https://buildbot.libretro.com/nightly/apple/tvos-arm64/latest/). You can also use the update-cores.sh script in the RetroArch source tree to fetch the cores from the buildbot for you: ```shell ./pkg/apple/update-cores.sh [--tvos] [core name]... ``` Without any arguments, it will try to update all of the cores in `pkg/apple/iOS/modules`. If there are no cores already downloaded, it will list the cores that are available to download. Any arguments are treated as core names and it will try to download that core if it is not already available. ### Building Cores Instead of downloading pre-built cores, you can build the cores yourself. The easiest way to build all the cores is to use libretro-super. To build for iOS 11 and up, run: ```shell ./libretro-build-ios-arm64.sh ``` To build cores for iOS 9 and up, run: ```shell ./libretro-build-ios9.sh ``` To build cores for iOS 6 to 8, run: ```shell ./libretro-build-ios.sh ``` In case you only want to build one and/or more cores instead of all, you can specify the cores you want to build after the first command in no particular order. E.g.: ```shell ./libretro-build-ios-arm64.sh snes9x2010 fceumm ``` Once finished, you can find the libretro cores inside directory `dist/ios-arm64`, `dist/ios9` or `dist/ios` depending on which build script you ran. ### Code Signing the Cores Note that you *must code sign the dylib cores* in order for you to use them. #### In iOS 9 and above Starting from iOS 9, the cores must be packaged as part of the application, even if they are code-signed. This was an additional security measure introduced in iOS 9. Fortunately, the code signing is handled as part of the Xcode build/archive process, so all you need to do is place your compiled `.dylib` cores in the `pkg/apple/iOS/modules` folder. Running the application via Xcode or archiving the application for an adhoc distribution will codesign the cores as long as they are placed in the aforementioned `pkg/apple/iOS/modules` folder. #### In iOS 6 to 8 You need to manually code sign the cores, and then you can copy them to the `Documents/RetroArch/cores` directory using an application like "iFunBox" or "iExplorer". ```shell cd [path where the dylib cores are] codesign -fs '[Your Full Developer Certificate Name]' *.dylib ``` ## Building RetroArch There are multiple Xcode project files in `pkg/apple`, based on minimum iOS version. The following will use `pkg/apple/RetroArch_iOS13.xcodeproj` (the latest as of this writing) as an example. 1. Open Xcode. 1. Open the following project file `pkg/apple/RetroArch_iOS13.xcodeproj` 1. Change the identifiers and signing for the target 1. In the Navigator Pane on the left, select the `Retroarch_iOS13` project 1. In the Project and Targets list on the left side, choose the `RetroArchiOS` (or `RetroArchTV` for tvOS) target. Select the Target (the one with the RetroArch icon), not the project. 1. In the `Signing & Capabilities` tab, change the "Team" under Signing to be your developer name. 1. In the `Signing & Capabilities` tab, Change the "Bundle Identifier" to something globally unique (e.g. `your.email.address.RetroArch`). 1. Change the signing for the extensions 1. In the Navigator Pane on the left, select the `Retroarch_iOS13` project 1. In the Project and Targets list on the left side, choose the `RetroArchWidgetExtensionExtension` (or `RetroArchTopShelfExtension` for tvOS) target. 1. In the `Signing & Capabilities` tab, change the "Team" under Signing to be your developer name. 1. In the `Signing & Capabilities` tab, Change the "Bundle Identifier" to the bundle identifier you chose for the target plus a suffix (e.g. `your.email.address.RetroArch.RetroArchWidgetExtension`). 1. For tvOS, in order for Top Shelf to work, you additionally need to set up the App Groups properly, described below. 1. Set the active scheme to `RetroArch iOS Release` (or `RetroArch tvOS Release` for tvOS), and select your connected iOS/tvOS device as the device. 1. Run (**⌘-R**) ![Xcode Steps](../../../image/guides/ios-install-pic-1.png) Once the application has been built, installed, and run on your device, it can be run again directly from the device without needing Xcode. ## App Store Build Building for the Mac App Store requires being logged into Xcode with the Apple Developer account associated with the Bundle ID for the app. The app also builds with Push Notification and CloudKit entitlements for the iCloud cloud sync driver (and Top Shelf for tvOS). Once all of the signing and entitlements are set up, creating the build is simply changing the scheme to `RetroArch AppStore`. There is an automated [fastlane](http://docs.fastlane.tools) script available in pkg/apple/fastlane that will update the build numbers and upload the built prodduct to TestFlight using an [App Store Connect API Key](http://docs.fastlane.tools/app-store-connect-api/). ## Additional Tips: ### Cores - When you run RetroArch and try to run a game, and see the message "Failed to load libretro core", that means the core is not code signed. See the above "Code Signing the Cores" section on making sure your cores are signed. You can manually check the code signature on a file by doing: `codesign -dvv mednafen_psx_libretro_ios.dylib`. The Authority entry has your certificate - make sure it's your dev or adhoc distribution certificate. - To see if your core is valid and usable in RetroArch, you can also try Load Core and selecting the core. If you see the core name appear at the top (in the GUI menu), then it is properly codesigned and loaded. If you still see "No Core", then your core is not codesigned and cannot be used. ### Top Shelf Top Shelf for tvOS will display up to five entries from each of the History and Favorites playlists, but is not compiled by default. The Top Shelf extension runs as in a different sandbox, and sharing the playlists requires the use of App Groups. In order to enable the Top Shelf extension: 1. With the project selected, select the RetroArchTV target. In the `Signing & Capabilities` tab, add the `App Groups` capability, and provide a unique group identifier. 2. You will also need to provide a unique app/bundle identifier. This will have the effect of breaking updating from a prior version of the app, as the app data will not be copied over due to the new bundle identifier. 3. Select the RetroArchTopShelfExtension target. In the `Signing & Capabilities` tab, add the `App Groups` capability, and provide the same unique group identifier. 4. You will also need to provide a unique app/bundle identifier for the extension. 5. In `pkg/apple/RetroArchTopShelfExtension/ContentProvider.h`, change the value of `kRetroArchAppGroup` to be the same unique group identifier. ### Development #### Where do I start? The RetroArch codebase can be daunting, especially if you're used to iOS development in Objective C or Swift. Objective C is a superset of C so the syntax should look somewhat familiar to you. The first and main entrypoint you should look at is in `core/griffin/griffin.c`. This is where all the code is included, with compiler flags used to bring in code specific to the platform. For iOS, you should pay attention to the compiler flags like `__APPLE__`, `TARGET_OS_IPHONE`, `HAVE_COCOATOUCH`. Note that you can Cmd-click into the `#include` paths to peer into the source code. You can also Cmd-Shift-O and type in the source file as well. And, breakpoints work as well! The iOS specific code is in `core/griffin/griffin_objc.m`. Here you'll find the include to `./ui/drivers/ui_cocoatouch.m`, which contains the application delegate - the main entry point for the iOS application lifecycle. From there everything should look familiar to you as an iOS developer, and you should be able to hook in any iOS specific objective c code. Although you can use Objective C data structures and code, you'll probably be having to use C data structures since you'll have to call methods in C to hook back into RetroArch, and they will expect C data structures. The great thing is you can mix C code with Objective C, as long as you do the necessary conversions to the data structures that RetroArch expects. ================================================ FILE: docs/development/retroarch/compilation/linux-and-bsd.md ================================================ # Compilation in Linux and BSD Compilation on Linux and BSD does not have many surprises, as its foundation is Unix-based. ### Dependencies - At least one libretro implementation - pkgconfig - Working OpenGL headers (should be included by default, but you might need to install libgl/mesa development packages) ### Optional dependencies - libxml2-devel - For XML shaders and cheat support. - libcaca-devel - Color AsCii Art library - freetype-devel - TTF font rendering - ffmpeg/libavcodec - FFmpeg recording - flac-devel - Free Lossless Audio Codec - nvidia-cg-toolkit - Cg shaders - slang-devel - Slang shaders - libudev-devel - qt5-qtbase-devel - For Qt GUI (Desktop) - zlib-devel Some other libraries can be built support for as well, please refer to `./configure --help`. #### Satisfying dependencies under Fedora 23 ```bash sudo dnf install make automake gcc gcc-c++ kernel-devel mesa-libEGL-devel libv4l-devel libxkbcommon-devel mesa-libgbm-devel Cg libCg zlib-devel freetype-devel libxml2-devel ffmpeg-devel SDL2-devel SDL-devel perl-X11-Protocol perl-Net-DBus pulseaudio-libs-devel openal-soft-devel libusb-devel ``` #### Satisfying additional dependencies under Fedora 33 ```bash sudo dnf install egl-wayland-devel wayland-devel wayland-protocols-devel mesa-vulkan-devel libXxf86vm-devel flac-devel slang-devel libcaca-devel qt5-qtbase-devel ``` #### Satisfying dependencies under Debian/Ubuntu ```bash apt-get -y install build-essential libxkbcommon-dev zlib1g-dev libfreetype6-dev libegl1-mesa-dev libgles2-mesa-dev libgbm-dev nvidia-cg-toolkit nvidia-cg-dev libavcodec-dev libsdl2-dev libsdl-image1.2-dev libxml2-dev yasm ``` #### Satisfying dependencies under Alpine ```sh apk add eudev-dev ffmpeg-dev freetype-dev g++ gcc libxml2-dev mesa-dev pkgconf zlib-dev ``` This list of packages may not be complete. ### Getting the code ```bash git clone https://github.com/libretro/libretro-super.git cd libretro-super SHALLOW_CLONE=1 ./libretro-fetch.sh ``` ### Building RetroArch ```bash ./retroarch-build.sh ``` ### Building libretro cores You should at least build one libretro implementation so RetroArch can do stuff. There is a [super-project](https://github.com/libretro/libretro-super) that is designed to easily build every libretro port out there. To build every core: ```bash NOCLEAN=1 ./libretro-build.sh ``` Omit NOCLEAN=1 if you wish to perform "make clean" on every repo before building ### Installing Let's assume you'd like to install RetroArch into a folder called `~/ra` ```bash mkdir -p ~/ra/cores cd retroarch make DESTDIR=~/ra install cd .. #to libretro-super directory ./libretro-install.sh ~/ra/cores ``` You should now have a fully functional RetroArch build in `~/ra` Enjoy! :) ================================================ FILE: docs/development/retroarch/compilation/msvc-runtime-versions.md ================================================ # MSVC Runtime Versions |VC++ version |_MSC_VER|Alternative name |C runtime |C++ runtime | |-------------|--------|-------------------------|---------------|--------------| |1.0 |800 | |MSVCRT10.DLL | | |2.0 |900 | |MSVCRT20.DLL | | |4.0 |1000 | |MSVCRT40.DLL | | |4.2 |1020 | |MSVCRT.DLL | | |5.0 |1100 |Visual Studio 97 |MSVCRT.DLL |MSVCP50.DLL | |6.0 |1200 |Visual Studio 6.0, VC98 |MSVCRT.DLL |MSVCP60.DLL | |7.0 |1300 |Visual Studio .NET (2002)|MSVCR70.DLL |MSVCP70.DLL | |7.1 |1310 |Visual Studio .NET 2003 |MSVCR71.DLL |MSVCP71.DLL | |8.0 |1400 |Visual Studio 2005 |MSVCR80.DLL |MSVCP80.DLL | |9.0 |1500 |Visual Studio 2008 |MSVCR90.DLL |MSVCP90.DLL | |10.0 |1600 |Visual Studio 2010 |MSVCR100.DLL |MSVCP100.DLL | |11.0 |1700 |Visual Studio 2012 |MSVCR110.DLL |MSVCP110.DLL | |12.0 |1800 |Visual Studio 2013 |MSVCR120.DLL |MSVCP120.DLL | |14.0 |1900 |Visual Studio 2015 |See notes |MSVCP140.DLL | |14.1* |1910* |Visual Studio 2017 |See notes |MSVCP140.DLL | !!! Note "Note for VC2003" The runtime does not have its own redist, it is instead only bundled with .NET Framework 1.1, or you can manually extract it from KB932298 (2007 DST Update). !!! Note "Note for VC2015/2017" The runtime was split into 4 external libraries: concrt140.dll, msvcp140.dll, vccorlib140.dll and vcruntime140.dll, as well as an OS-local component named ucrtbase.dll included with Windows 10 and up. !!! Note "Note for VC2017" The version numbers increment with each update (VC++ versions 14.1/14.11/14.12, _MSC_VER 1910/1911/1912, Visual Studio versions 15.0/15.3/15.5 etc.). And yes, the C++ runtime is still called VCP140 and not VCP141... ## What does my Windows version ship with? |Version |NT3 |95 |NT4 |98 |2000 |ME |XP |2003 |2003R2|Vista|2008 |7 |2008R2|2012 |8 |8.1 |2012R2|10 |2016 | |:---------:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:----:|:---:|:---:|:---:|:----:|:---:|:---:|:---:|:----:|:---:|:---:| |1.0 |X | | | | | | | | | | | | | | | | | | | |2.0 |X |X |X |X |X | |X |X |X |X |X |X |X |X |X |X |X |X |X | |4.0 | |X* |X |X |X | |X |X |X |X |X |X |X |X |X |X |X |X |X | |5.0 | | | |X* |X | |X |X |X | | | | | | | | | | | |6.0 | | | | | | |X |X |X |X |X |X |X |X |X |X |X |X |X | |2002 | | | | | | | | | | | | | | | | | | | | |2003 | | | | | | | |X* |X* | | | | | | | | | | | |2005 | | | | | | | | | |X |X |X |X |X |X |X |X |X |X | |2008 | | | | | | | | | | | |X |X |X |X |X |X |X |X | |2010 | | | | | | | | | | | | | |X | | |X | |X | |2012 | | | | | | | | | | | | | | | | | | |X | |2013 | | | | | | | | | | | | | | | | | | | | |2015 | | | | | | | | | | | | | | | | | | | | |2017 | | | | | | | | | | | | | | | | | | | | !!! Note "Note for Windows 95" The VC40 runtime is only bundled with Windows 95B (OSR2) and up. !!! Note "Note for Windows 98" The VC50 runtime is not always installed, but is available on the install CD (in WIN98/WIN98_36.CAB for First Edition and 37.CAB for Second Edition). !!! Note "Note for Server 2003 and 2003R2" The VC2003 runtime requires installing the .NET Framework via the Windows Components Wizard after installation. ## Which runtime is supported by my Windows version? From [Minimum service pack levels for Microsoft VC++ Redistributable Packages](https://support.microsoft.com/en-us/help/2661358/minimum-service-pack-levels-for-microsoft-vc-redistributable-packages): |Version |95 |NT4 |98 |2000 |ME |XP |2003 |2003R2|Vista|2008 |7 |2008R2|2012 |8 |8.1 |2012R2|10 |2016 | |:---------:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:----:|:---:|:---:|:---:|:----:|:---:|:---:|:---:|:----:|:---:|:---:| |2003 |X* |SP6a*|X* |X* |X* |X* |X* |X* |X* |X* | | | | | | | | | |2005 | | | | | |SP2+ |SP1+ | | | | | | | | | | | | |2005 SP1 | | | | | |SP2+ |SP1+ |X |X |X |X |X |X |X |X |X |X | | |2008 | | | |SP4 | |SP2+ |SP1+ |X |X | | | | | | | | | | |2008 SP1 | | | | | |SP2+ |SP1+ |X |X |X |X |X |X |X |X |X |X | | |2010 | | | | | |SP3 |SP2+ |X |SP2+ |SP2+ |X |X* | | | | | | | |2010 SP1 | | | | | |SP3 |SP2+ |X |SP2+ |SP2+ |X |X* |X* |X* |X* |X* |X* | | |2012 Upd. 4| | | | | |SP3 |SP2+ |X |SP2+ |SP2+ |SP1+ |SP1+ |X |X |X |SP1+* |X | | |2013 | | | | | |SP3 |SP2+ |X |SP2+ |SP2+ |SP1+ |SP1+ |X |X |X |X |X | | |2015 | | | | | |SP3 |SP2+ |X |SP2+ |SP2+ |SP1+ |SP1+ |X |X |X |X |X | | |2017 | | | | | |SP3 |SP2+ | |SP2+ |SP2+ |SP1+ |SP1+ |X | |X* | |X* |X | !!! Note "Note for VC2003" The VC2003 runtime is not provided as a separate download and requires installing the .NET Framework 1.1 (requires IE 5.01 or later). !!! Note "Note for VC2010" Server 2008R2 requires SP1 if using the x64 version. !!! Note "Note for VC2010 SP1" MS Documentation is conflicting about whether or not 2008R2/2012 x86 is supported, or if 8/2012 or higher is even supported at all. !!! Note "Note for VC2012 Update 4/VC2013" MS Documentation is conflicting about the exact service pack levels and architectures supported for each OS version. !!! Note "Note for VC2013" For 8.1 and 2012R2, KB2883200 is required. !!! Note "Note for VC2017" For 8.1 and 2012R2, KB2919355 is required. For 10, build 1507 or later is required. Requirements were taken from [here](https://docs.microsoft.com/en-us/visualstudio/productinfo/vs2017-system-requirements-vs). !!! Note "Note for Windows 7/8/2012 and higher" While some runtimes may not be documented as officially supported, testing shows that all the above versions appear to work. ================================================ FILE: docs/development/retroarch/compilation/osx.md ================================================ # macOS/OSX Compilation / Development Guide This compilation guide will teach you how to build RetroArch for macOS/OSX. All versions of the operating system since 10.5 are supported. RetroArch can work on PPC, Intel, and ARM processor-powered Macs. This video covers a quick demonstration of these subjects; 1. Environment Configuration 2. Fetching the code 3. Building RetroArch 4. (Optional) Building the cores Be sure to read instructions that are given on this page. ## Environment configuration ### Xcode The only requirement for building is Xcode, which is only available for macOS. You can get Xcode from the App Store. If you have never used Xcode before, you will need to open the Xcode preferences, and in Accounts, log in with your Apple ID. ### retroarch-apple-deps (optional but recommended) RetroArch optionally will automatically link with supporting libraries (including MoltenVK) that are provided by the retroarch-apple-deps repo. By default Xcode will look for these dependencies in `/usr/local/share/retroarch-apple-deps`. To get retroarch-apple-deps, run: ```shell git clone https://github.com/warmenhoven/retroarch-apple-deps.git retroarch-apple-deps sudo ln -s $PWD/retroarch-apple-deps /usr/local/share ``` ## Fetching the code ### libretro-super The recommended way of fetching RetroArch source code, as well as the source code for all of the cores, is to use libretro-super. To get libretro-super, run: ```shell git clone https://github.com/libretro/libretro-super.git libretro-super cd libretro-super ``` Now you can run the following command to download the source for RetroArch: ```shell ./libretro-fetch.sh --retroarch ``` You can run the following command to download the source for RetroArch as well as all of the cores: ```shell ./libretro-fetch.sh ``` Or specify just the cores that you want: ```shell ./libretro-fetch.sh snes9x2010 fceumm ``` ### RetroArch repo If you choose not to use libretro-super, you can clone RetroArch's repository from [GitHub](https://github.com/libretro/RetroArch) ```shell git clone https://github.com/libretro/RetroArch.git retroarch cd retroarch ``` !!! Note Versions of git available for OSX PowerPC might not come with the necessary SSL/TLS support that Github now requires. If you happen to find that you can not clone or pull from Github, perform the following command: git config --global http.sslVerify false. For subsequent builds you only need to pull the changes from the repo ```shell cd retroarch git pull ``` To update your local copy from the repository run git pull ## RetroArch Compilation There are several Xcode projects and workspaces in the `pkg/apple` directory in RetroArch, to choose from based on your needs: | Xcode Project/Workspace File Name | OS support | Purpose | -----------------------------------------|-|- | `RetroArch.xcworkspace` | 10.13+ | The primary workspace for the latest Metal build. Most active development happens here. | | `RetroArch_Metal.xcodeproj` | 10.13+ | The project for the latest Metal build. You can use this directly but typically it's preferred to use the Workspace. | | `RetroArch.xcodeproj` | 10.6+ | The outdated non-Metal build, only for Intel processor-powered Macs. | | `RetroArch_PPC.xcodeproj` | 10.5+ | Building for PowerPC processor-powered Macs. | | `RetroArch_OSX107.xcodeproj` | 10.7+ | An old development line that is no longer in use. | ### Building RetroArch separately Open Xcode. Open your chosen project file in the Xcode IDE and build (**⌘-B**) and run (**⌘-R**) it there. The default scheme should be `RetroArch` and that is what is used for building the DMG image available on the buildbot. ## Core Compilation (optional) RetroArch on OSX by default will be configured to download cores from the buildbot; you do not need to build the cores yourself. ### libretro-super (deprecated) If you choose to build the cores yourself, the easiest way to build all the cores is to use libretro-super. To build all cores for OSX, run ```shell ./libretro-build.sh ``` In case you only want to build one and/or more cores instead of all, you can specify the cores you want to build after the first command in no particular order. E.g.: ```shell ./libretro-build.sh snes9x2010 fceumm ``` Once finished, you can find the libretro cores inside directory `dist/osx`. ### GitLab CI mimicry Cores on the buildbot are built using the GitLab CI infrastructure. Each core provides its own `.gitlab-ci.yml` file with instructions for how to build it. Almost all cores reference one of the [CI Templates](https://git.libretro.com/libretro-infrastructure/ci-templates). Between the `.gitlab-ci.yml` file and the templates, you should have complete instructions for how to build each core. ## Store Builds ### Steam Build Building for Steam differs from the normal app build in two ways: the scheme is `RetroArchSteam`, and it requires bundling [mist](https://git.libretro.com/libretro-steam/mist) and linking against libmist. Simply download the latest artifacts for mist from GitLab, and set the `MIST_PATH` variable in the Xcode project with its location. Once the Steam app is built, it is no different from the app available in the Steam store, and will communicate with Steam to fetch cores and update presence. ### Mac App Store Build Building for the Mac App Store requires being logged into Xcode with the Apple Developer account associated with the Bundle ID for the app. The app also builds with Push Notification and CloudKit entitlements for the iCloud cloud sync driver. Once all of the signing and entitlements are set up, creating the build is simply changing the scheme to `RetroArch AppStore`. There is an automated [fastlane](http://docs.fastlane.tools) script available in pkg/apple/fastlane that will update the build numbers and upload the built prodduct to TestFlight using an [App Store Connect API Key](http://docs.fastlane.tools/app-store-connect-api/). ================================================ FILE: docs/development/retroarch/compilation/ps2.md ================================================ # PlayStation 2 Compilation / Development Guide ## Environment configuration You need the homebrew PlayStation 2 SDK and toolchain installed. You can follow how to install the toolchain over here [ps2toolchain](https://github.com/ps2dev/ps2toolchain) Additionally you need the PS2 Graphics Synthesizer installed. You can follow how to install the GSKit over here [gsKit](https://github.com/ps2dev/gsKit) Finally you need to install specific ports for PlayStation 2. You can follow how to install the PlayStation 2 Ports over here [ps2sdk-ports](https://github.com/ps2dev/ps2sdk-ports) ## RetroArch Compilation ### Fetching RetroArch Clone RetroArch's repository from [GitHub](https://github.com/libretro/RetroArch) git clone https://github.com/libretro/RetroArch.git retroarch cd retroarch For subsequent builds you only need to pull the changes from the repo cd retroarch git pull To update your local copy from the repository run git pull ### Building RetroArch separately To compile RetroArch (for PlayStation 2) run: make -f Makefile.ps2 !!! Note RetroArch on PlayStation PS2 is statically linked. With statically linked RetroArch, each executable is a separate libretro core instead of the core being separately loaded from a single executable. A pre-existing libretro library needs to be present in the root directory in order to link RetroArch PS2. This file needs to be called 'libretro_ps2.a'. After a few seconds/minutes you should be able to find a retroarch_ps2.elf file under that directory. ### Building RetroArch in bulk Instead of building each core one by one, you can build all cores as a batch task. Run from the main 'retroarch' directory: cd dist-scripts !!! Note Make sure that all the libretro cores that you want to compile are inside the 'dist-scripts' directory. Once inside this directory, run : This process will also automate the packaging process for you. ### Packaging RetroArch ### Additional Tips: ## Core Compilation ### Fetching Cores The easiest way to fetch all the cores is to use libretro-super. Run ./libretro-fetch.sh ### Building Cores The easiest way to build all the cores (for PlayStation Portable) is to use libretro-super. Run In case you only want to build one and/or more cores instead of all, you can specify the cores you want to build after the first command in no particular order. E.g.: Once finished, you can find the libretro cores inside directory `dist/ps2`. ================================================ FILE: docs/development/retroarch/compilation/psp.md ================================================ # PlayStation PSP Compilation / Development Guide ## Environment configuration You need the homebrew PlayStation PSP SDK and toolchain installed. ## RetroArch Compilation ### Fetching RetroArch Clone RetroArch's repository from [GitHub](https://github.com/libretro/RetroArch) git clone https://github.com/libretro/RetroArch.git retroarch cd retroarch For subsequent builds you only need to pull the changes from the repo cd retroarch git pull To update your local copy from the repository run git pull ### Building RetroArch separately First, you need to compile [Salamander](../glossary.md#salamander). To compile Salamander (for PlayStation Portable) run: make -f Makefile.psp1.salamander Second, to compile RetroArch (for PlayStation Portable) run: make -f Makefile.psp1 !!! Note RetroArch on PlayStation PSP is statically linked. With statically linked RetroArch, each executable is a separate libretro core instead of the core being separately loaded from a single executable. A pre-existing libretro library needs to be present in the root directory in order to link RetroArch Vita. This file needs to be called 'libretro_psp1.a'. After a few seconds/minutes you should be able to find a retroarch_psp1.elf and retroarch_psp1.self file under that directory. ### Building RetroArch in bulk Instead of building each core one by one, you can build all cores as a batch task. Run from the main 'retroarch' directory: cd dist-scripts !!! Note Make sure that all the libretro cores that you want to compile are inside the 'dist-scripts' directory. Once inside this directory, run : ./dist-cores.sh psp1 This process will also automate the packaging process for you. ### Packaging RetroArch ### Additional Tips: ## Core Compilation ### Fetching Cores The easiest way to fetch all the cores is to use libretro-super. Run ./libretro-fetch.sh ### Building Cores The easiest way to build all the cores (for PlayStation Portable) is to use libretro-super. Run ./libretro-build-psp1.sh In case you only want to build one and/or more cores instead of all, you can specify the cores you want to build after the first command in no particular order. E.g.: ./libretro-build-psp1.sh snes9x2010 fceumm Once finished, you can find the libretro cores inside directory `dist/psp1`. ================================================ FILE: docs/development/retroarch/compilation/psvita.md ================================================ # PlayStation Vita/TV Compilation / Development Guide ## Environment configuration You need the homebrew PlayStation Vita SDK and toolchain installed. ## RetroArch Compilation ### Fetching RetroArch Clone RetroArch's repository from [GitHub](https://github.com/libretro/RetroArch) git clone https://github.com/libretro/RetroArch.git retroarch cd retroarch For subsequent builds you only need to pull the changes from the repo cd retroarch git pull To update your local copy from the repository run git pull ### Building RetroArch separately First, you need to compile [Salamander](../glossary.md#salamander). To compile Salamander (for PlayStation3) run: make -f Makefile.vita.salamander Second, to compile RetroArch (for PlayStation3) run: make -f Makefile.griffin platform=vita !!! Note RetroArch on PlayStation Vita/TV is statically linked. With statically linked RetroArch, each executable is a separate libretro core instead of the core being separately loaded from a single executable. A pre-existing libretro library needs to be present in the root directory in order to link RetroArch Vita. This file needs to be called 'libretro_vita.a'. After a few seconds/minutes you should be able to find a retroarch_vita.elf and retroarch_vita.self file under that directory. ### Building RetroArch in bulk Instead of building each core one by one, you can build all cores as a batch task. Run from the main 'retroarch' directory: cd dist-scripts !!! Note Make sure that all the libretro cores that you want to compile are inside the 'dist-scripts' directory. Once inside this directory, run : ./dist-cores.sh vita This process will also automate the packaging process for you. ### Packaging RetroArch ### Additional Tips: ## Core Compilation ### Fetching Cores The easiest way to fetch all the cores is to use libretro-super. Run ./libretro-fetch.sh ### Building Cores The easiest way to build all the cores (for PlayStation3) is to use libretro-super. Run ./libretro-build-vita.sh In case you only want to build one and/or more cores instead of all, you can specify the cores you want to build after the first command in no particular order. E.g.: ./libretro-build-vita.sh snes9x2010 fceumm Once finished, you can find the libretro cores inside directory `dist/vita`. ================================================ FILE: docs/development/retroarch/compilation/switch-libnx.md ================================================ # Nintendo Switch Compilation / Development Guide (libnx) ## Environment configuration You need the homebrew Nintendo Switch SDK libnx and DevkitA64 toolchain installed. You can find instructions on how to install it on the [switchbrew wiki](https://switchbrew.org/wiki/Setting_up_Development_Environment). Then, install all the required libraries: - use the devkitpro MSYS2 terminal on Windows - replace `dkp-pacman` by `pacman` on Linux and Mac OS ``` dkp-pacman -Sy devkit-env devkitA64 libnx switch-tools switch-mesa switch-zlib switch-bzip2 switch-liblzma switch-freetype switch-libpng switch-libvpx switch-ffmpeg switch-libopus ``` ## RetroArch Compilation All commands must be issued in the devkitpro environment (MSYS2 on Windows). ### Fetching RetroArch Clone RetroArch's repository from [GitHub](https://github.com/libretro/RetroArch) ``` git clone https://github.com/libretro/RetroArch.git retroarch cd retroarch ``` For subsequent builds you only need to pull the changes from the repo ``` cd retroarch git pull ``` ### Building Cores The easiest way to build all the cores (for Switch) is to use [libretro-super](https://github.com/libretro/libretro-super). `git clone` and `cd` into the base directory, then run: ``` make -f Makefile.libnx ``` In case you only want to build one and/or more cores instead of all, you can specify the cores you want to build using the commands below. E.g.: ``` ./libretro-fetch.sh snes9x2010 fceumm platform=libnx ./libretro-build.sh snes9x2010 fceumm ``` Once finished, you can find the libretro cores inside directory `dist/libnx`. ### Building RetroArch Each NRO of RetroArch has one and only one core, and each core is a standalone homebrew by itself. That means that building multiple cores means building RetroArch multiple times, once for each core. The cores you previously built will be called `_libretro_libnx.a`, where `` is the name of the core that was used to build it. For each core you wish to build, you will need to copy it to the `retroarch` directory, and rename it to `libretro_libnx.a`. Once the core has been moved and renamed, move to the `retroarch` directory using `cd` and run this command: ``` make -f Makefile.libnx ``` That will output `retroarch_switch.nro`: this is your home built copy of RetroArch! It is recommended to rename your '.nro' file so you can remember which core it contains. You can then use `nxlink` to send the homebrew to your Switch over Wi-Fi. ================================================ FILE: docs/development/retroarch/compilation/ubuntu.md ================================================ # Ubuntu Compilation / Development Guide ## Environment configuration The easiest route to get into building RetroArch and libretro cores on Ubuntu linux is to use libretro's PPA. For stable releases you can add the PPA like this: # add-apt-repository ppa:libretro/stable # apt-get update For development work we recommend the testing PPA instead: # add-apt-repository ppa:libretro/testing # apt-get update You will need **git** and a few build tools at least to proceed which you can install by issuing the following command: # apt-get install git build-essential ## RetroArch Compilation ### Building RetroArch The first step is to obtain RetroArch's source tree. $ git clone https://github.com/libretro/RetroArch.git retroarch You can get RetroArch's dependenencies by running the following command: # apt-get build-dep retroarch !!! Note Depending on your configuration you may need to uncomment the *deb-src* repositories in */etc/apt/sources.list*, */etc/apt/sources.list.d/libretro-ubuntu-testing-$version.list* and then run **apt-get update** before running **apt-get build-dep** For subsequent builds you will need to pull the changes from the repo $ cd retroarch $ git pull To compile RetroArch run the following commands inside RetroArch's source tree: $ ./configure $ make clean $ make -j4 For development purposes you might want to run a debug build instead. In such case use the following commands: $ ./configure $ make clean $ make DEBUG=1 GL_DEBUG=1 -j4 You can then start RetroArch by running: $ ./retroarch Local builds do not contain assets. On a clean build, assets will be located by default at *$HOME/.config/retroarch/assets*, and can be downloaded from the Main Menu via Online Updater > Update Assets !!! tip If you're building frequently you may want to add **ccache** to the mix to speed up the build process. Install ccache via apt and the prepend the ccache symlink directory to your build environment path as shown below. For further instructions check the [documentation](https://ccache.samba.org/manual.html#_run_modes) Install **ccache**: # apt-get install ccache Configure paths: $ export PATH=/usr/lib/ccache/bin/:$PATH !!! tip You can add that last line to your *~/.bashrc* to avoid having to type that every time you start your working environment. ## Core Compilation ### Fetching Cores You can find the cores on libretro's [GitHUB organization](https://github.com/libretro/). We have an all-in-one tool to fetch and compile cores which you can use to streamline the process. You can obtain the tool by using these commands: $ git clone https://github.com/libretro/libretro-super.git $ cd libretro-super Then you can fetch one or all the cores by using **libretro-fetch.sh** Fetch all cores: $ ./libretro-fetch.sh Fetch one core: $ ./libretro-fetch.sh *corename* !!! Note Replace *corename* with the name of the core you want to fetch, for example gambatte ### Building Cores #### LibRetro Super The easiest way to build all the cores is to use **libretro-build.sh** from within libretro-super's source tree: $ ./libretro-build.sh In case you only want to build one and/or more cores instead of all, you can specify the cores you want to build after the first command in no particular order: $ ./libretro-build.sh snes9x2010 fceumm Once compilation has finished, you can find the libretro cores inside *dist/unix*. #### Manual Fetching and Compilation Get the core's source tree. As an example we'll use [fceumm](https://github.com/libretro/libretro-fceumm/) $ git clone https://github.com/libretro/libretro-fceumm.git Then compile the core: $ cd libretro-fceumm $ make -f Makefile.libretro Optionally strip the build product: $ strip fceumm_libretro.so Most cores will build with these instructions. You might need to browse to a subdirectory in some cases. ================================================ FILE: docs/development/retroarch/compilation/wii.md ================================================ # Nintendo Wii Compilation / Development Guide ## Environment configuration You need to have installed [devkitPro](https://github.com/devkitPro/installer/releases), the homebrew Nintendo Wii SDK (libOGC) and the devkitPPC (r29 or r29-1) toolchain on your computer. ## RetroArch Compilation ### Fetching RetroArch Clone RetroArch's repository from [GitHub](https://github.com/libretro/RetroArch) git clone https://github.com/libretro/RetroArch.git retroarch --recursive cd retroarch For subsequent builds you only need to pull the changes from the repo cd retroarch git pull To update your local copy of the RetroArch repository, run git pull ### Building RetroArch separately First, you need to compile [Salamander](../glossary.md#salamander). To compile Salamander (for Wii) run: make -f Makefile.wii.salamander Rename the file retroarch-salamander_wii.dol as boot.dol. This file is the frontend launcher for the other cores (indeed files containing core and frontend). Second, to compile RetroArch for Wii (the core and the frontend), rename the compiled core as 'libretro_wii.a' (see below how to compile a core in the "Building Cores" section), put it in the RetroArch directory and run: make -f Makefile.griffin platform=wii !!! Note RetroArch on Wii is statically linked. With statically linked RetroArch, each executable is a separate libretro core instead of the core being separately loaded from a single executable. A pre-existing libretro library needs to be present in the root directory in order to link RetroArch Wii. This file needs to be called 'libretro_wii.a'. After a few seconds/minutes you should be able to find a retroarch_wii.elf and retroarch_wii.dol file under that directory. ### Building RetroArch in bulk Instead of building each core one by one, you can build all cores as a batch task. Run from the main 'retroarch' directory: cd dist-scripts !!! Note Make sure that all the libretro cores that you want to compile are inside the 'dist-scripts' directory. Once inside this directory, run : ./dist-cores.sh wii This process will also automate the packaging process for you. ### Packaging RetroArch ### Additional Tips: ## Core Compilation ### Fetching Cores The easiest way to fetch all the cores is to use libretro-super. Download libretro-super from [GitHub](https://github.com/libretro/libretro-super) and run ./libretro-fetch.sh ### Building Cores The easiest way to build all the cores (for Wii) is to use libretro-super. If not already fetched, put the codes of the cores you want compile in the libretro-super directory and run ./libretro-build-wii.sh In case you only want to build one and/or more cores instead of all, you can specify the cores you want to build after the first command in no particular order. E.g.: ./libretro-build-wii.sh snes9x2010 fceumm Once finished, you can find the libretro cores inside directory `dist/wii`. Another way to compile cores, is by cloning the core's repository (for example, FCEUmm) from [GitHub](https://github.com/orgs/libretro/repositories). In this case, to clone FCEUmm-Libretro repo: git clone https://github.com/libretro/libretro-fceumm.git libretro-fceumm --recursive cd libretro-fceumm For subsequent builds you only need to pull the changes from the core's repo (ex., FCEUmm) cd libretro-fceumm git pull To update your local copy from the repository of the core (in this case FCEUmm), run git pull To compile the core for Wii (in this case, FCEUmm) run: make platform=wii Some cores (example, Snes9x) have a dedicated makefile for compile as a Libretro core. To compile the core for Wii with the dedicated Libretro makefile run: make -f Makefile.libretro platform=wii Rename the compiled core as 'libretro_wii.a', then put it in the RetroArch directory and follow the instructions in the "Building RetroArch separately" section. ================================================ FILE: docs/development/retroarch/compilation/wiiu.md ================================================ # Nintendo Wii U Compilation / Development Guide ## Environment configuration You need the DevkitPPC(r29) toolchain installed and the DEVKITPRO and DEVKITPPC environment variables set to the respective folders. ## RetroArch Compilation ### Fetching RetroArch Clone RetroArch's repository from [GitHub](https://github.com/libretro/RetroArch) git clone https://github.com/libretro/RetroArch.git retroarch cd retroarch For subsequent builds you only need to pull the changes from the repo cd retroarch git pull To update your local copy from the repository run git pull ### Building RetroArch separately To compile RetroArch (for Wii U) run: make -f Makefile.wiiu !!! Note RetroArch on Wii U is statically linked. With statically linked RetroArch, each executable is a separate libretro core instead of the core being separately loaded from a single executable. A pre-existing libretro library needs to be present in the root directory in order to link RetroArch Wii U. This file needs to be called 'libretro_wiiu.a'. After a few seconds/minutes you should be able to find a retroarch_wiiu.elf and retroarch_wiiu.rpx file under that directory. ### Building RetroArch in bulk Instead of building each core one by one, you can build all cores as a batch task. Run from the main 'retroarch' directory: cd dist-scripts !!! Note Make sure that all the libretro cores that you want to compile are inside the 'dist-scripts' directory. you can also copy the [info files](https://github.com/libretro/libretro-super/tree/master/dist/info) and [icons](https://github.com/libretro/retroarch-assets/tree/master/pkg/wiiu) in the same directory to have them added to the package, and to generate the meta.xml files. Once inside this directory, run : ./wiiu-cores.sh This process will also automate the packaging process for you. the output will be in `pkg/wiiu`. ### Packaging RetroArch ### Additional Tips: ## Core Compilation ### Fetching Cores The easiest way to fetch all the cores is to use libretro-super. Run ./libretro-fetch.sh ### Building Cores The easiest way to build all the cores (for Wii U) is to use libretro-super. Run ./libretro-build-wiiu.sh In case you only want to build one and/or more cores instead of all, you can specify the cores you want to build after the first command in no particular order. E.g.: ./libretro-build-wiiu.sh snes9x2010 fceumm Once finished, you can find the libretro cores inside directory `dist/wiiu`. ================================================ FILE: docs/development/retroarch/compilation/windows.md ================================================ # Windows 7 and later compilation and development guide !!! Warning The MinGW toolchain we use in this guide no longer supports targeting Windows Vista or earlier. Please refer to one of the MSVC guides for how to target older Windows versions with Visual Studio. This video covers quick demonstrations of these subjects; 1. Environment Configuration 2. Building RetroArch 3. Packaging RetroArch Be sure to read instructions that are given in this page. ## Environment configuration We recommend MinGW-W64 from MSYS2. You can download MSYS2 installer from [here](http://msys2.github.io/). Follow the installation instructions and once finished start the MSYS2 shell. You may need to add "Full Control" permission to your MSYS folder (for example, C:\msys64) or run the shell as Administrator. MSYS2 shell is a maintenance shell. We are going to use this shell to install the toolchain and other packages. First order of business is to update MSYS2. Start the MSYS2 MINGW64 or MINGW32 Shell (mingw64.exe or mingw32.exe), It is important to use this particular shell (MINGW) because the makefile uses it to detect the target platform as Windows. Once we're in the shell, run the following commands: ```bash pacman --noconfirm -Sy pacman --needed --noconfirm -S bash pacman pacman-mirrors msys2-runtime ``` Close MSYS2 shell and start it again, and: ```bash pacman --noconfirm -Su ``` Restart MSYS2 once again. Now we can start installing the packages we actually need. For 32-bit builds: ```bash pacman -S --noconfirm --needed wget git make mingw-w64-i686-toolchain mingw-w64-i686-ntldd mingw-w64-i686-zlib mingw-w64-i686-pkg-config mingw-w64-i686-SDL2 mingw-w64-i686-libxml2 mingw-w64-i686-freetype mingw-w64-i686-python3 mingw-w64-i686-ffmpeg mingw-w64-i686-drmingw ``` For 64-bit builds: ```bash pacman -S --noconfirm --needed wget git make mingw-w64-x86_64-toolchain mingw-w64-x86_64-ntldd mingw-w64-x86_64-zlib mingw-w64-x86_64-pkg-config mingw-w64-x86_64-SDL2 mingw-w64-x86_64-libxml2 mingw-w64-x86_64-freetype mingw-w64-x86_64-python3 mingw-w64-x86_64-ffmpeg mingw-w64-x86_64-drmingw ``` You might want to install Qt too if you want to be able to use the desktop GUI. For 32-bit builds: ```bash pacman -S --noconfirm --needed mingw-w64-i686-qt5 mingw-w64-i686-openssl ``` For 64-bit builds: ```bash pacman -S --noconfirm --needed mingw-w64-x86_64-qt5 mingw-w64-x86_64-openssl ``` The NVIDIA CG toolkit package hasn't been updated for a while so you need to download that package manually and install with pacman. You can download the packages from sourceforge at the following locations: [32-bit](http://sourceforge.net/projects/msys2/files/REPOS/MINGW_GCC_4_9/i686/mingw-w64-i686-nvidia-cg-toolkit-3.1-2-any.pkg.tar.xz/download) / [64-bit](http://sourceforge.net/projects/msys2/files/REPOS/MINGW_GCC_4_9/x86_64/mingw-w64-x86_64-nvidia-cg-toolkit-3.1-2-any.pkg.tar.xz/download). Alternatively you can use the following commands directly: For 32-bit builds: ```bash wget http://sourceforge.net/projects/msys2/files/REPOS/MINGW_GCC_4_9/i686/mingw-w64-i686-nvidia-cg-toolkit-3.1-2-any.pkg.tar.xz/download -O mingw-w64-i686-nvidia-cg-toolkit-3.1-2-any.pkg.tar.xz pacman -U mingw-w64-i686-nvidia-cg-toolkit-3.1-2-any.pkg.tar.xz ``` For 64-bit builds: ```bash wget https://sourceforge.net/projects/mingw-w64-archlinux/files/x86_64/mingw-w64-nvidia-cg-toolkit-3.1-2-any_4.pkg.tar.xz/download -O mingw-w64-x86_64-nvidia-cg-toolkit-3.1-2-any.pkg.tar.xz pacman -U mingw-w64-x86_64-nvidia-cg-toolkit-3.1-2-any.pkg.tar.xz ``` If you encounter any errors, you may try the following procedure instead: ```bash pacman -S mingw-w64-x86_64-crt pacman -S mingw-w64-x86_64-nvidia-cg-toolkit ``` Once these packages are installed close MSYS2 shell and open MinGW-w32 shell or MinGW-w64 shell depending on the platform you want to build for. You'll need gcc and make: ```bash pacman -S make pacman -S gcc ``` ## RetroArch Compilation ### Building RetroArch The first step is to obtain RetroArch's source tree. You can find the repository directly at [GitHub](https://github.com/libretro/RetroArch) Start the MINGW64 or the MINGW32 shell depending on what you want to compile and run the following commands: ```bash git clone https://github.com/libretro/RetroArch.git retroarch ``` For subsequent builds you will need to pull the changes from the repo ```bash cd retroarch git pull ``` To compile RetroArch, run the following commands inside RetroArch's source tree: ```bash ./configure make clean make -j4 ``` For development purposes you might want to run a debug build instead. In such case use the following commands: ```bash ./configure make clean make DEBUG=1 GL_DEBUG=1 -j4 ``` To facilitate debugging you can get an integrated crash handler by replacing the configure step with (debug builds only): ./configure --enable-drmingw After a few minutes you should be able to find retroarch.exe under that directory. To start the newly compiled retroarch you can use: ```bash ./retroarch ``` ### Packaging RetroArch You might not be able to start your own build outside that environment. You might want to try to get all the required DLLs by running the following script in your destination RetroArch folder (not the git repo folder): ```bash for i in $(seq 3); do for bin in $(ntldd -R *exe | grep -i mingw | cut -d">" -f2 | cut -d" " -f2); do cp -vu "$bin" . ; done; done ``` If Qt is enabled for your build (detected automatically by default), the following is also needed: ```bash windeployqt --no-patchqt --no-translations retroarch.exe for i in $(seq 3); do for bin in $(ntldd -R imageformats/*dll | grep -i mingw | cut -d">" -f2 | cut -d" " -f2); do cp -vu "$bin" . ; done; done ``` If you really want to get the required libraries for distribution or for personal use on other devices and LDD doesn't work for you for whatever reason, then you can try [Dependency Walker](http://www.dependencywalker.com/). !!! tip If you're building frequently you may want to add **ccache** to the mix to speed up the build process. Install ccache via the package manager and the prepend the ccache symlink directory to your build environment path as shown below. For further instructions check the [documentation](https://ccache.samba.org/manual.html#_run_modes) Install **ccache** for 32-bit builds: ```bash pacman -S --noconfirm --needed make mingw-w64-i686-ccache ``` Install **ccache** for 64-bit builds: ```bash pacman -S --noconfirm --needed mingw-w64-x86_64-ccache ``` Configure paths for 32-bit builds: ```bash export PATH=/mingw32/lib/ccache/bin/:$PATH ``` Configure paths for 64-bit builds: ```bash export PATH=/mingw64/lib/ccache/bin/:$PATH ``` Build with both `ccache` and the `-j5` flag to specify five concurrent tasks: ```bash ccache make -j5 ``` !!! tip You can add this to /etc/profile under both the 32-bit and 64-bit setups by adding `${MINGW_MOUNT_POINT}/lib/ccache/bin` to the front of the PATH variables found in `MINGW32)` and `MINGW64)`, around line 50 of profile, to ensure the proper binaries are loaded for each development environment. From our own buildbot, the times with and without **ccache** are the following: Without **ccache**: real 2m7.645s user 0m2.585s sys 0m11.527s With **ccache**: real 0m25.466s user 0m2.902s sys 0m9.952s !!! tip You can also strip the debug symbols of the build product to save some space. Strip **retroarch**: ```bash strip -s retroarch.exe ``` ## Core Compilation ### Fetching Cores You can find the cores on libretro's [GitHUB organization](https://github.com/libretro/). We have an all-in-one tool to fetch and compile cores which you can use to streamline the process. You can obtain the tool by using these commands: ```bash git clone https://github.com/libretro/libretro-super.git cd libretro-super ``` Then you can fetch one or all the cores by using **libretro-fetch.sh** Fetch all cores: ```bash ./libretro-fetch.sh ``` Fetch one core: ```bash ./libretro-fetch.sh *corename* ``` !!! Note Replace *corename* with the name of the core you want to fetch, for example gambatte ### Building Cores #### libretro-super The easiest way to build all the cores is to use **libretro-build.sh** from within libretro-super's source tree: ```bash ./libretro-build.sh ``` In case you only want to build one and/or more cores instead of all, you can specify the cores you want to build after the first command in no particular order: ```bash ./libretro-build.sh snes9x2010 fceumm ``` Once compilation has finished, you can find the libretro cores inside *dist/win*. #### Manual Fetching and Compilation Get the core's source tree. As an example we'll use [fceumm](https://github.com/libretro/libretro-fceumm/) ```bash git clone https://github.com/libretro/libretro-fceumm.git ``` Then compile the core: ```bash cd libretro-fceumm make -f Makefile.libretro ``` If the Makefile.libretro is not present, as in the libretro-atari800 core, you might try the following: ```bash cd libretro-atari800 make ``` Optionally strip the build product: ```bash strip fceumm_libretro.dll ``` Most cores will build with these instructions. You might need to browse to a subdirectory in some cases. ================================================ FILE: docs/development/retroarch/compilation/windows2000-msvc-cmdline.md ================================================ # Windows (2000 and later) Command-line Compilation / Development Guide ## Environment configuration To compile RetroArch on the command-line targeting Windows 2000 or later, we will use a combination of the MSYS2 shell and Microsoft Visual C++ 2008. This guide assumes the host OS is Windows Vista or later, as MSYS2 cannot be installed on anything older. Prerequisites: [Visual C++ 2008 Express](http://download.microsoft.com/download/A/9/1/A91D6B2B-A798-47DF-9C7E-A97854B7DD18/VC.iso) (or Pro) ## RetroArch Compilation ### Building RetroArch First you will need the MSYS2 distribution. You can download the MSYS2 installer from [here](http://msys2.github.io/). Follow the installation instructions and once finished start the MSYS2 shell. First we need to install the `make` package: pacman -S make Then we need to obtain RetroArch's source tree. You can clone the repository directly from [GitHub](https://github.com/libretro/RetroArch): git clone https://github.com/libretro/RetroArch.git retroarch For subsequent builds you will need to pull the changes from the repo cd retroarch git pull To compile RetroArch, run: make -f Makefile.griffin platform=windows_msvc2008_x86 If you do not want to compile in DirectX support, you can add `HAVE_DIRECTX=0` to the end of the command line. Currently it is necessary to disable DirectX support when targeting NT4. ### Finished After the build is finished you should be able to find retroarch.exe in the current directory. To start the newly compiled retroarch, copy the .exe file to a new folder where its configuration files and folders will be automatically created on first run. Running the .exe file inside of the source directory is not recommended as it will overwrite existing files. ================================================ FILE: docs/development/retroarch/compilation/windows2000.md ================================================ # Windows (2000 and later) Compilation / Development Guide ## Environment configuration To compile RetroArch targeting Windows 2000 or later, we will use Microsoft Visual C++ 2008. This is the last version of Visual C++ that can target 2000. Prerequisites: [Visual C++ 2008 Express](http://download.microsoft.com/download/A/9/1/A91D6B2B-A798-47DF-9C7E-A97854B7DD18/VC.iso) (or Pro) ## RetroArch Compilation ### Building RetroArch !!! Note Setting up a working git shell is beyond the scope of this document. The first step is to obtain RetroArch's source tree. You can clone the repository directly from [GitHub](https://github.com/libretro/RetroArch) git clone https://github.com/libretro/RetroArch.git retroarch For subsequent builds you will need to pull the changes from the repo cd retroarch git pull To compile RetroArch, first open the solution file located at pkg/msvc/RetroArch-msvc2008.sln with Visual C++ 2008. Next we select the desired solution configuration: ![configurations](https://s3.amazonaws.com/retroarch/msvc2005-targets.png) The choices are: Debug Debug NoAccel Release Release NoAccel For development purposes you can use the Debug configurations, otherwise use Release. The "NoAccel" versions do not include Direct3D or OpenGL support (but keeps DirectInput and DirectSound support). Now press F7 to build the solution, or go to Build -> Build Solution. After the build is finished you should be able to find RetroArch-msvc2008.exe in the pkg/msvc/msvc-2008/<configuration> directory, where `` is the one you chose earlier such as Debug or Release. To start the newly compiled retroarch you can press F5 in Visual C++ or simply navigate to the .exe file and run it there. ================================================ FILE: docs/development/retroarch/compilation/windows95-msvc-cmdline.md ================================================ # Windows (95/98/NT4) Command-line Compilation / Development Guide ## Environment configuration To compile RetroArch on the command-line targeting Windows 95, Windows 98 or Windows NT4, we will use a combination of the MSYS2 shell and Microsoft Visual Studio .NET 2003. This guide assumes the host OS is Windows Vista or later, as MSYS2 cannot be installed on anything older. Prerequisites: Visual Studio .NET 2003 [Windows Server 2003 SP1 Platform SDK](https://www.microsoft.com/en-us/download/details.aspx?id=12261) !!! Note Windows 95 does not support DirectX 9.0, and NT4 does not support DirectX higher than 3.0a. !!! Note In lieu of having to install the full Visual Studio suite, a minimal toolchain can be created by copying the `Common7` and `Vc7` folders from an installation on another machine (usually located at `C:\Program Files (x86)\Microsoft Visual Studio .NET 2003`). For this example we will use a root folder of `C:\mini-msvc` to hold everything, and those two folders from the MSVC installation will be copied into a directory under the root folder called `msvc2003`. !!! Note The same thing can be done with the Platform SDK, just copy the `Include` and `Lib` folders from an existing installation (usually located in `C:\Program Files (x86)\Microsoft Platform SDK`) into a folder in the root such as `plat2003sp1`. ## RetroArch Compilation ### Building RetroArch First you will need the MSYS2 distribution. You can download the MSYS2 installer from [here](http://msys2.github.io/). Follow the installation instructions and once finished start the MSYS2 shell. First we need to install the `make` package: pacman -S make Then we need to obtain RetroArch's source tree. You can clone the repository directly from [GitHub](https://github.com/libretro/RetroArch): git clone https://github.com/libretro/RetroArch.git retroarch For subsequent builds you will need to pull the changes from the repo cd retroarch git pull To compile RetroArch, run: make -f Makefile.griffin platform=windows_msvc2003_x86 DirectX support is disabled by default since 95/NT do not support DirectX 9.0, but if you will only be running on higher versions of Windows, you can re-enable it by adding `HAVE_DIRECTX=1` to the end of the command line. ### Minimal Toolchain If you are only using a minimal toolchain as described above, you can instead specify the location of the `msvc2003` and `plat2003sp1` folders like this: make -f Makefile.griffin platform=windows_msvc2003_x86 VS71COMNTOOLS="c:\\mini-msvc\\msvc2003\\Common7\\Tools\\" INETSDK="c:\\mini-msvc\\plat2003sp1" !!! Note The trailing slash at the end of the COMNTOOLS variable is mandatory. Also, any of the paths can optionally be left out to use the system version instead. ### Finished After the build is finished you should be able to find retroarch.exe in the current directory. To start the newly compiled retroarch, copy the .exe file to a new folder where its configuration files and folders will be automatically created on first run. Running the .exe file inside of the source directory is not recommended as it will overwrite existing files. ================================================ FILE: docs/development/retroarch/compilation/windows98-msvc-cmdline.md ================================================ # Windows (98 SE/ME/2000) Command-line Compilation / Development Guide ## Environment configuration To compile RetroArch on the command-line targeting Windows NT4, Windows 98SE, Windows Millenium Edition or Windows 2000, we will use a combination of the MSYS2 shell and Microsoft Visual C++ 2005. This guide assumes the host OS is Windows Vista or later, as MSYS2 cannot be installed on anything older. Prerequisites: [DirectX SDK February 2005](https://s3.amazonaws.com/bparker/dxsdk_feb2005.exe) (any version up to December 2006 should work to target 98SE) [Visual C++ 2005 Express](http://download.microsoft.com/download/A/9/1/A91D6B2B-A798-47DF-9C7E-A97854B7DD18/VC.iso) (or Pro) [Windows Server 2003 SP1 Platform SDK](https://www.microsoft.com/en-us/download/details.aspx?id=12261) !!! Note Windows 98 Second Edition is supported, but First Edition has not been tested. If you do try to target it, make sure that your DirectX SDK is no newer than July 2004. !!! Note In lieu of having to install the full Visual Studio suite, a minimal toolchain can be created by copying the `Common7` and `VC` folders from an installation on another machine (usually located at `C:\Program Files (x86)\Microsoft Visual Studio 8`). For this example we will use a root folder of `C:\mini-msvc` to hold everything, and those two folders from the MSVC installation will be copied into a directory under the root folder called `msvc2005`. !!! Note The same thing can be done with the DirectX and Platform SDKs, just copy the `Include` and `Lib` folders from an existing installation (usually located at `C:\Program Files (x86)` in `Microsoft DirectX SDK (June 2010)` and `Microsoft Platform SDK` respectively) into folders in the root such as `dx9_june2010` and `plat2003sp1`. ## RetroArch Compilation ### Building RetroArch First you will need the MSYS2 distribution. You can download the MSYS2 installer from [here](http://msys2.github.io/). Follow the installation instructions and once finished start the MSYS2 shell. First we need to install the `make` package: pacman -S make Then we need to obtain RetroArch's source tree. You can clone the repository directly from [GitHub](https://github.com/libretro/RetroArch): git clone https://github.com/libretro/RetroArch.git retroarch For subsequent builds you will need to pull the changes from the repo cd retroarch git pull To compile RetroArch, run: make -f Makefile.griffin platform=windows_msvc2005_x86 If you do not want to compile in DirectX support, you can add `HAVE_DIRECTX=0` to the end of the command line. Currently it is necessary to disable DirectX support when targeting NT4. ### Minimal Toolchain If you are only using a minimal toolchain as described above, you can instead specify the location of the folders `msvc2005`, `dx9_feb2005` and `plat2003sp1` like this: make -f Makefile.griffin platform=windows_msvc2005_x86 VS80COMNTOOLS="c:\\mini-msvc\\msvc2005\\Common7\\Tools\\" INETSDK="c:\\mini-msvc\\plat2003sp1" DXSDK_DIR="c:\\mini-msvc\\dx9_feb2005" !!! Note The trailing slash at the end of the COMNTOOLS variable is mandatory. Also, any of the paths can optionally be left out to use the system version instead. ### Finished After the build is finished you should be able to find retroarch.exe in the current directory. To start the newly compiled retroarch, copy the .exe file to a new folder where its configuration files and folders will be automatically created on first run. Running the .exe file inside of the source directory is not recommended as it will overwrite existing files. ================================================ FILE: docs/development/retroarch/compilation/windows98.md ================================================ # Windows (98/2000) Compilation / Development Guide ## Environment configuration To compile RetroArch targeting Windows 98 and 2000, we will use Microsoft Visual C++ 2005. This is the last version of Visual C++ that can target 98/2000. This guide assumes the host OS is Windows 2000 Professional. VC2005 does run on Windows XP and Vista but this has not been tested with RetroArch. Prerequisites: [Windows 2000 Service Pack 4](https://web.archive.org/web/20051022095019/http://download.microsoft.com/download/e/6/a/e6a04295-d2a8-40d0-a0c5-241bfecd095e/w2ksp4_en.exe) [Windows 2000 Update Rollup 1](https://web.archive.org/web/20060320020710/http://download.microsoft.com/download/2/7/b/27b1d1a3-0299-4336-b88a-22b9f09817e2/Windows2000-KB891861-v2-x86-ENU.EXE) [Internet Explorer 6](https://s3.amazonaws.com/bparker/ie60.exe) [Internet Explorer 6 Service Pack 1](https://s3.amazonaws.com/bparker/IE6.0SP1-KB2722913-WINDOWS2000-X86-ENU.EXE) (required by VC2005) [DirectX SDK February 2005](https://s3.amazonaws.com/bparker/dxsdk_feb2005.exe) (versions after this date will not install on Windows 2000) [Windows Server 2003 SP1 Platform SDK](https://www.microsoft.com/en-us/download/details.aspx?id=12261) [Visual C++ 2005 Express](http://download.microsoft.com/download/A/9/1/A91D6B2B-A798-47DF-9C7E-A97854B7DD18/VC.iso) (or Pro) !!! Note Windows 98 Second Edition is supported, but First Edition has not been tested. If you do try to target it, make sure that your DirectX SDK is no newer than July 2004. ## RetroArch Compilation ### Building RetroArch !!! Note Setting up a working git shell is beyond the scope of this document. [msysgit 1.8.5.2](https://github.com/msysgit/msysgit/releases/download/Git-1.8.5.2-preview20131230/Git-1.8.5.2-preview20131230.exe) is known to work locally but is unable to communicate with any remote servers on Windows 2000, and the github website does not load in IE6 either. The first step is to obtain RetroArch's source tree. You can clone the repository directly from [GitHub](https://github.com/libretro/RetroArch) git clone https://github.com/libretro/RetroArch.git retroarch For subsequent builds you will need to pull the changes from the repo cd retroarch git pull To compile RetroArch, first open the solution file located at pkg/msvc/RetroArch-msvc2005.sln with Visual C++ 2005. Next we select the desired solution configuration: ![configurations](https://s3.amazonaws.com/retroarch/msvc2005-targets.png) The choices are: Debug Debug NoAccel Release Release NoAccel For development purposes you can use the Debug configurations, otherwise use Release. The "NoAccel" versions do not include Direct3D or OpenGL support (but keeps DirectInput and DirectSound support). Now press F7 to build the solution, or go to Build -> Build Solution. After the build is finished you should be able to find RetroArch-msvc2005.exe in the pkg/msvc/msvc-2005/<configuration> directory, where `` is the one you chose earlier such as Debug or Release. To start the newly compiled retroarch you can press F5 in Visual C++ or simply navigate to the .exe file and run it there. ================================================ FILE: docs/development/retroarch/compilation/windowsNT351-msvc-cmdline.md ================================================ # Windows (NT3.51) Command-line Compilation / Development Guide ## Environment configuration To compile RetroArch on the command-line targeting Windows NT3.51, we will use a combination of the MSYS2 shell and Microsoft Visual C++ 6. This guide assumes the host OS is Windows Vista or later, as MSYS2 cannot be installed on anything older. Prerequisites: Visual C++ 6 [Windows Server 2003 SP1 Platform SDK](https://www.microsoft.com/en-us/download/details.aspx?id=12261) !!! Note In lieu of having to install the full Visual Studio suite, a minimal toolchain can be created by copying the `Common` and `VC98` folders from an installation on another machine (usually located at `C:\Program Files (x86)\Microsoft Visual Studio`). For this example we will use a root folder of `C:\mini-msvc` to hold everything, and those two folders from the MSVC installation will be copied into a directory under the root folder called `msvc6`. !!! Note The same thing can be done with the Platform SDK, just copy the `Include` and `Lib` folders from an existing installation (usually located in `C:\Program Files (x86)\Microsoft Platform SDK`) into a folder in the root such as `plat2003sp1`. ## RetroArch Compilation ### Building RetroArch First you will need the MSYS2 distribution. You can download the MSYS2 installer from [here](http://msys2.github.io/). Follow the installation instructions and once finished start the MSYS2 shell. First we need to install the `make` package: pacman -S make Then we need to obtain RetroArch's source tree. You can clone the repository directly from [GitHub](https://github.com/libretro/RetroArch): git clone https://github.com/libretro/RetroArch.git retroarch For subsequent builds you will need to pull the changes from the repo cd retroarch git pull To compile RetroArch, run: make -f Makefile.griffin platform=windows_msvc6_x86 ### Minimal Toolchain If you are only using a minimal toolchain as described above, you can instead specify the location of the `msvc6` and `plat2003sp1` folders like this: make -f Makefile.griffin platform=windows_msvc6_x86 VCDIR="c:\\mini-msvc\\msvc6\\VC98" INETSDK="c:\\mini-msvc\\plat2003sp1" Also, any of the paths can optionally be left out to use the system version instead. ### Finished After the build is finished you should be able to find retroarch.exe in the current directory. To start the newly compiled retroarch, copy the .exe file to a new folder where its configuration files and folders will be automatically created on first run. Running the .exe file inside of the source directory is not recommended as it will overwrite existing files. ================================================ FILE: docs/development/retroarch/compilation/windowsXP-msvc-cmdline.md ================================================ # Windows (XP and later) Command-line Compilation / Development Guide ## Environment configuration To compile RetroArch on the command-line targeting Windows XP or later, we will use a combination of the MSYS2 shell and Microsoft Visual Studio 2010. This guide assumes the host OS is Windows Vista or later, as MSYS2 cannot be installed on anything older. Prerequisites: [DirectX SDK June 2010](https://www.microsoft.com/en-us/download/details.aspx?id=6812) [Visual Studio 2010 Express](http://web.archive.org/web/20161014172355/http://download.microsoft.com/download/1/E/5/1E5F1C0A-0D5B-426A-A603-1798B951DDAE/VS2010Express1.iso) (or Pro) !!! Note The Express version does not come with a 64-bit compiler. [Visual Studio 2010 Service Pack 1](http://web.archive.org/web/20160401071422/http://download.microsoft.com/download/E/B/A/EBA0A152-F426-47E6-9E3F-EFB686E3CA20/VS2010SP1dvd1.iso) (needed for the multi-language support in RetroArch) !!! Note In lieu of having to install the full Visual Studio suite, a minimal toolchain can be created by copying the `Common7` and `VC` folders from an installation on another machine (usually located at `C:\Program Files (x86)\Microsoft Visual Studio 10.0`). For this example we will use a root folder of `C:\mini-msvc` to hold everything, and those two folders from the MSVC installation will be copied into a directory under the root folder called `msvc2010`. !!! Note The same thing can be done with the DirectX SDK, just copy the `Include` and `Lib` folders from an existing installation (usually located at `C:\Program Files (x86)\Microsoft DirectX SDK (June 2010)`) into a folder in the root such as `dx9_june2010`. ## RetroArch Compilation ### Building RetroArch First you will need the MSYS2 distribution. You can download the MSYS2 installer from [here](http://msys2.github.io/). Follow the installation instructions and once finished start the MSYS2 shell. First we need to install the `make` package: pacman -S make Then we need to obtain RetroArch's source tree. You can clone the repository directly from [GitHub](https://github.com/libretro/RetroArch): git clone https://github.com/libretro/RetroArch.git retroarch For subsequent builds you will need to pull the changes from the repo cd retroarch git pull To compile RetroArch, run: make -f Makefile.griffin platform=windows_msvc2010_x86 Replace x86 with x64 if you would like a 64-bit build instead of 32-bit. If you do not want to compile in DirectX support, you can add `HAVE_DIRECTX=0` to the end of the command line. ### Minimal Toolchain If you are only using a minimal toolchain as described above, you can instead specify the location of the `msvc2010` and `dx9_june2010` folders like this: make -f Makefile.griffin platform=windows_msvc2010_x86 VS100COMNTOOLS="c:\\mini-msvc\\msvc2010\\Common7\\Tools\\" DXSDK_DIR="c:\\mini-msvc\\dx9_june2010" !!! Note The trailing slash at the end of the COMNTOOLS variable is mandatory. Also, any of the paths can optionally be left out to use the system version instead. ### Finished After the build is finished you should be able to find retroarch.exe in the current directory. To start the newly compiled retroarch, copy the .exe file to a new folder where its configuration files and folders will be automatically created on first run. Running the .exe file inside of the source directory is not recommended as it will overwrite existing files. ================================================ FILE: docs/development/retroarch/compilation/windowsXP.md ================================================ # Windows (XP and later) Compilation / Development Guide ## Environment configuration To compile RetroArch targeting Windows XP or later, we will use Microsoft Visual Studio 2010. This guide assumes the host OS is Windows XP. Prerequisites: [Windows XP Service Pack 3](https://support.microsoft.com/en-us/help/936929/information-about-windows-xp-service-pack-3) (requires SP1 or SP2 installed first) [DirectX SDK June 2010](https://www.microsoft.com/en-us/download/details.aspx?id=6812) [Visual Studio 2010 Express](http://web.archive.org/web/20161014172355/http://download.microsoft.com/download/1/E/5/1E5F1C0A-0D5B-426A-A603-1798B951DDAE/VS2010Express1.iso) (or Pro) [Visual Studio 2010 Service Pack 1](http://web.archive.org/web/20160401071422/http://download.microsoft.com/download/E/B/A/EBA0A152-F426-47E6-9E3F-EFB686E3CA20/VS2010SP1dvd1.iso) (needed for the multi-language support in RetroArch) ## RetroArch Compilation ### Building RetroArch The first step is to obtain RetroArch's source tree. If you need a git shell to work in, [msysgit 1.8.5.2](https://github.com/msysgit/msysgit/releases/download/Git-1.8.5.2-preview20131230/Git-1.8.5.2-preview20131230.exe) is known to work. You can clone the repository directly from [GitHub](https://github.com/libretro/RetroArch): git clone https://github.com/libretro/RetroArch.git retroarch For subsequent builds you will need to pull the changes from the repo cd retroarch git pull To compile RetroArch, first open the solution file located at pkg/msvc/RetroArch-msvc2010.sln with Visual Studio 2010. Next we select the desired solution configuration: ![configurations](https://s3.amazonaws.com/retroarch/msvc2010-targets.png) The choices are: Debug Debug Cg Release Release Cg For development purposes you can use the Debug configurations, otherwise use Release. The "Cg" versions also include support for Cg shaders used with the OpenGL video driver. These will require a separate installation of the [Nvidia Cg Toolkit](https://developer.nvidia.com/cg-toolkit). Now press F7 to build the solution, or go to Build -> Build Solution. After the build is finished you should be able to find RetroArch-msvc2005.exe in the pkg/msvc/<configuration> directory, where `` is the one you chose earlier such as Debug or Release. To start the newly compiled retroarch you can press F5 in Visual C++ or simply navigate to the .exe file and run it there. ================================================ FILE: docs/development/retroarch/debugging.md ================================================ # Debugging ## Dr.MinGW Windows debug builds now have an integrated crash handler. If you find any recurrent crashes you can start the retroarch_debug.exe executable, reproduce the crash and you should find a time-stamped crash log in the retroarch directory. ## GDB (All platforms) The [GNU Debugger](https://www.gnu.org/software/gdb/) is the most widely available debugging tool for many platforms. !!! note "Windows users" This guide assumes you have already installed the MSYS2/MinGW environment as detailed [here](../../compilation/windows/) and that you are running in the appropriate "MSYS2 MinGW" (32 or 64-bit) shell (not "MSYS2 MSYS"). If you observe a crash with RetroArch and would like to get more information, navigate to the folder where your RetroArch installation is and run: > gdb retroarch !!! note "Windows users" If you have not compiled RetroArch yourself with debugging enabled (`make DEBUG=1`), please specify `retroarch_debug.exe` here instead of `retroarch` to use the debug version that ships with our binary package. In order to debug in Windows 10 when the D3D10 or D3D11 video drivers are in use, be sure that you have also [installed Microsoft's free Windows Direct3D Graphics Tools package](https://docs.microsoft.com/en-us/windows/uwp/gaming/use-the-directx-runtime-and-visual-studio-graphics-diagnostic-features). After gdb has started, you can then start up RetroArch with `run`. If RetroArch crashes, gdb should show you a prompt with a message such as: `Program received signal SIGSEGV, Segmentation fault.` From here, type `bt full` to get a full backtrace of the crash. You can copy/paste this information to a pastebin site such as [dpaste](http://www.dpaste.com/) to get a link that you can provide to developers to help with your problem. Run `quit` when you are done to exit gdb. To get a full backtrace of the crash for all threads, type `thread apply all bt full`. For more information on using GDB, please see their online documentation [here](https://sourceware.org/gdb/current/onlinedocs/gdb/). ## ASAN (Linux/Mac/BSD/Android) AddressSanitizer (ASAN) is a very fast memory error detector and an indispensable tool for finding issues with improper memory handling such as use-after-free, buffer overflows and general memory leaks. It is available since GCC 4.8 and Clang 3.1 for Linux (x64 and ARM) systems. Typical slowdown of runtime performance is around 2x. There are several ways to use RetroArch in conjunction with ASAN and there are many different options that can be combined with each other. The first step is that you need to compile ASAN directly into the RetroArch binary. Here are some simple examples: **For detecting memory errors/leaks and undefined behavior:** > make DEBUG=1 SANITIZER=address,undefined **For detecting threading errors such as race conditions:** > make DEBUG=1 SANITIZER=thread Then you can run the RetroArch binary normally with `./retroarch`. As problems are detected, they will be printed to the console either at runtime or when the program exits or crashes, depending on the type of error. For more information, see the [gcc](https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html), [Google](https://github.com/google/sanitizers/wiki/AddressSanitizer) and [clang](https://clang.llvm.org/docs/) documentation. ## Dr. Memory (Windows/Linux/Mac/Android) Dr. Memory is another tool for detecting memory errors similar to ASAN. Its website can be found here: [http://www.drmemory.org/](http://www.drmemory.org/) After installation, the simplest way to use Dr. Memory with RetroArch is to open the start menu shortcut under "Dr. Memory" called "Explore Dr. Memory", and then drag the `retroarch_debug.exe` file onto the `drmemory.exe` file there. No re-compilation is necessary to use this tool. Any errors encountered will be displayed in a notepad window after the program exits or crashes. ## VulnScan (Windows/Linux) Also known as Microsoft Security Risk Detection, is a new memory error detection tool that is (at the time of writing) in closed beta status. For more information, please see its website [here](https://www.microsoft.com/en-us/security-risk-detection/). ## Valgrind (Linux) [Valgrind](http://valgrind.org/) is probably the oldest and most well known memory error and leak detector available. Here is an example command-line usage to run valgrind with RetroArch to check for memory or threading errors: > valgrind -v --tool=memcheck --leak-check=yes --track-origins=yes --show-reachable=yes ./retroarch No recompilation is necessary to use this tool, but make sure to run it using a debug build of RetroArch (built with `make DEBUG=1`). Some users have reported a large number of false positives with this tool, as well as much slower runtime performance, so in general we typically recommend to use ASAN instead if that is an option for you. ## rr (Linux) [rr](http://rr-project.org/) is a deterministic debugger that enhances gdb by supporting the recording and replay (and even reverse-replay) of your program's execution. Very useful for accurately reproducing a hard-to-trigger issue such as a race condition or crash that only occurs under certain conditions. For more information on using rr, please see their usage guide [here](https://github.com/mozilla/rr/wiki/Usage). ## Time Travel Debugging (Windows) [Time Travel Debugging](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/time-travel-debugging-overview) is a Windows tool for recording and replaying a program's execution, similar to [rr](http://rr-project.org/). For more information, please visit their website. ## Android Studio (Android) See [this file](https://github.com/libretro/RetroArch/blob/master/pkg/android/phoenix-gradle/README.md) for a guide on how to build, sideload and debug a core using Android Studio. ================================================ FILE: docs/development/retroarch/glossary.md ================================================ # Glossary While developing RetroArch, you might find some terms which are unfamiliar to new developers. These are explained here. ## Griffin Most of the console platforms of RetroArch use a concept we call 'Griffin'. Basically: - Every C file gets included in griffin/griffin.c. - Every C++ file gets included in griffin/griffin_cpp.cpp. - Every ObjectiveC file gets included in griffin_objc.m - Glslang files get included in griffin_glslang.cpp The Griffin files are the only ones being built when a platform port uses Griffin. This has a couple of benefits: - It's a poor man's kind of link time code generation optimization pass. - We dont have to keep editing every platform port's Makefile individually whenever we add a new file. We can simply update these Griffin files without touching any of the platform Makefiles. Some disadvantages (that we cater to regardless): - Because all of the C/C++/ObjC files all get included into one source file, it is necessary that all symbols and function names are uniquely named. We make sure in RetroArch this is the case. ## Salamander Salamander is a small RetroArch launcher for embedded platforms with static linking. On such platforms, each core binary contains the core and the complete RetroArch frontend. Switching cores is achieved by just re-launching into a different core binary. Salamander simply launches the most recently used core (or a default one, if none is stored in the config file). ================================================ FILE: docs/development/retroarch/input/input-drivers.md ================================================ # RetroArch Input Driver Specification [RetroArch](http://retroarch.com) is the reference frontend for the libretro API, and is used for emulators, game engines, and media players. RetroArch strives to be available on as many different platforms as possible. RetroArch runs and is supported on GNU/Linux, BSD, Windows, Mac OSX, Haiku, PlayStation Classic, PlayStation 2, PlayStation 3, Playstation Vita, Playstation Portable, Xbox 360, Xbox One, Raspberry Pi, Nintendo GameCube, Nintendo Wii, Nintendo Wii U, Nintendo 3DS & 2DS Family, Nintendo Switch, Steam Link, Android, iOS, Open Pandora, Blackberry, and in web browsers via the Emscripten compiler. ### Purpose of input drivers RetroArch uses a modular "driver" system to allow the software to be ported to new platforms. One or more RetroArch input drivers must be available on a system in order to run the frontend. In addition to input drivers, RetroArch uses a variety of other platform-specific drivers including video drivers, audio drivers, and video recording drivers. In RetroArch, choosing an input driver generally corresponds to choosing an input API on the host system. A RetroArch input driver might be written for the API of a piece of hardware, such as `input_wiiu`; it might be specific to an operating system, such as `input_linuxraw` or `input_dos`; or the driver might be available on several platforms, such as `input_sdl`. The input drivers implement access to user keyboards, mice, pointers, and lightguns. A "controller driver" is also necessary if the input driver implements access to user joysticks or gamepads. !!! Note Controller drivers were previously referred to as joypad drivers. Some documentation and code may still use the older "joypad" terminology. ### Purpose of this document This document organizes the information needed to develop and debug RetroArch input drivers, such as when porting RetroArch to a new platform. ## libretro input device abstractions RetroArch's input system is based on abstracted input device types which are polled via callbacks provided by the libretro API. Libretro input device abstractions include: * RetroPad - Digital Gamepad or Joystick - Digital Gamepad or Joystick with Analog * Mouse * Pointer * Keyboard * Lightgun ## RetroArch input priorities As the libretro reference frontend, RetroArch's goal is to implement the API in a way that provides users a full experience across as wide a variety of platforms as possible. This includes the ability to map and remap physical input hardware to as many different types of libretro input device abstractions as possible, although the amount of flexibility can vary due to the limitations of specific platforms. !!! Note The minimum API requirement for a libretro frontend is to implement polling responses for one "RetroPad", libretro's digital gamepad controller device abstraction. A compliant frontend could therefore support only a single input source -- for example, a frontend written for a handheld game system that has a built-in hardware controller, or a frontend that only accepts RetroPad input over a network connection. For libretro core developers, the value of a frontend like RetroArch that fully implements these abstractions with robust remapping abilities is that cores can be coded with the 'ideal' input type abstraction in mind using simple polling logic. Meanwhile users have the freedom to map that abstraction to any number of hardware or software input sources. ## Input driver functionality tables These tables presents RetroArch's input driver functionality organized into categories. It is based on the table that appears in the source for each input driver. Not all input drivers implement all possible functionality; in some case this is due to the inherent limitations of the host platform, and in other cases the functionality is possible but has yet to be implemented. | RetroPad Function | Supported | Notes | | ---------------------------------------------- | --------- | --------------------------------------- | | Map physical gamepad to RetroPad (Port 0) | | | | Map physical gamepad w/analog to RetroPad | | | | Support multiple RetroPads | | | | Remap one RetroPad control to another | | | | Map physical keyboard to RetroPad controls | | | | Map physical mouse buttons to RetroPad | | | | Map physical pointer taps/controls to RetroPad | | | | Keyboard Function | Supported | Notes | | ----------------------------------------------- | --------- | --------------------------------------- | | Map physical keyboard to RetroKeyboard | | | | Remap one RetroKey to another | | | | Respect `keyboard_mapping_blocked` | | | | Map physical gamepad controls to RetroKeys | | | | Map physical mouse buttons to RetroKeys | | | | Map physical pointer taps/controls to RetroKeys | | | | Mouse Function | Supported | Notes | | ---------------------------------------------------------- | --------- | --------------------------------------- | | Map physical mouse to RetroMouse (Port 0) | | | | Support multiple RetroMice | | | | 'Grab and ungrab' mice | | | | Remap one mouse control to another | | | | Map physical pointer/touchpad to RetroMouse | | | | Map physical analog controls to RetroMouse coordinates | | | | Map physical digital gamepad controls to RetroMouse buttons | | | | Map physical keyboard to RetroMouse buttons | | | | Pointer Function | Supported | Notes | | -------------------------------------------------------- | --------- | --------------------------------------- | | Map physical pointer/touchpad to RetroPointer (Port 0) | | | | Support Multi-Touch Pointer (Port 0) | | | | Support multiple RetroPointers | | | | Support Multiple Pointers w/Multi-Touch | | | | Support remapping one touchpad control to another | | | | Map physical mouse to RetroPointer | | | | Map physical analog controls to RetroPointer coordinates | | | | Map physical digital gamepad controls to taps/controls | | | | Map physical keyboard to taps/controls | | | | Lightgun Function | Supported | Notes | | ----------------------------------------------------- | --------- | --------------------------------------- | | Map physical pointer/touchpad to Lightgun (Port 0) | | | | Map physical mouse to Lightgun (Port 0) | | | | Map physical analog joysticks to Lightguns | | | | Support multiple Lightguns | | | | Map multiple mice to multiple Lightguns | | | | Map multiple pointers/touchpads to multiple Lightguns | | | | Map physical digital gamepad to Lightgun controls | | | | Map physical keyboard to Lightgun controls | | | | Sensor Function* | Supported | Notes | | ------------------------------------------ | --------- | --------------------------------------- | | Set polling rate | | | | Enable/disable sensors | | | | Get sensor input | | | !!! Note The **Sensor Function** table of input driver sensor functionality is incomplete. [Contributions welcome!](../../../meta/how-to-contribute.md) | Other Input Functions* | Supported | Notes | | ----------------------------------------------------------- | --------- | ------------------------------------ | | | | | !!! Note The **Other Input Functions** table of input driver functionality is driver-specific at this time. ## Input driver architecture To be written. ### input_driver_t struct To be written. #### Example input_driver_t ```c input_driver_t input_winraw = { winraw_init, winraw_poll, winraw_input_state, winraw_free, NULL, NULL, winraw_get_capabilities, "raw", winraw_grab_mouse, NULL }; ``` ## Documentation TODO * Some RetroArch video drivers also serve as input drivers. In cases when the video driver relies on input driver for event handling, the video driver can preinitialize an input driver. * Describe controller drivers and their implementation ================================================ FILE: docs/development/retroarch/input/overlay.md ================================================ # Overlays RetroArch supports overlay images for use with hardware accelerated drivers. The purpose of this is to allow some kind of input interface that is mouse/touch oriented. The overlay images are displayed with transparency over the regular game image, and the user is able to trigger input by pressing on certain parts of the overlay. Since the overlay is a series of images, the user should be able to fully configure the look and functionality of this overlay. This allows skinners and themers to go wild. ### Libretro overlay repositories The Libretro Organization hosts a repositories on Github that contains a compilation of overlays made with the Overlay Specification. * Interactive overlays are managed within: https://github.com/libretro/common-overlays * Decorative border overlays are managed within: https://github.com/libretro/overlay-borders ![RetroArch dinothawr overlay example](https://wiki.libretro.com/images/5/5c/Retroarch-dinothawr-overlay.jpg "RetroArch dinothawr overlay example") ## Configuration The overlay is described in a config file (.cfg). The config file uses the same config file syntax as RetroArch itself. The overlay system supports use of multiple overlays that can be switched out on the fly. Input is not only restricted to gamepad input, but can also work with any input that is bindable in RetroArch, e.g. save states, rewind, load state, etc. The config file describes: - Which full-screen overlay images to use (.png, .tga, etc). - The hitbox for each input event, i.e. "size" of the button. - Which image should be shown over the input descriptors individually (optional). - Where on the screen the entire overlay should be displayed. ## Overlay images First we configure how many overlays we use. Every overlay can have one overlay which fills the entire rectangle (overlay%u_rect), but is optional. The full-rect overlay is supported for compatibility with older format. It is less flexible than per-button overlays and is discouraged. overlays = 2 overlay0_overlay = overlay_img0.png # Optional overlay1_overlay = overlay_img1.png # Optional The paths are relative to where the overlay config is loaded from. If the path is absolute, absolute paths will be used. On Unix-like systems ~/ is recognized as $HOME/. ## Screen placement By default, the overlay image will be stretched out to fill the whole game image. However, for some overlays, this is not practical. It is possible to set the placement using for example: overlay0_rect = "0.2,0.3,0.5,0.4" We assume that the game screen has normalized coordinates in X and Y that span from [0, 0] in the top-left corner to [1, 1] in the lower-right corner. This will render the overlay to x = 0.2, y = 0.3 with size width = 0.5, height = 0.4. The default (stretch to full screen) could be described as such: overlay0_rect = "0.0,0.0,1.0,1.0" ## Full-screen vs. full-viewport overlays By default, overlays will be stretched out to fill game viewport. However, in some cases the aspect ratio of the game causes there to remain large black borders around the game image. It is possible to stretch the overlay to full screen (instead of viewport) by specifying this option: overlay0_full_screen = true ## Coordinate descriptors We must also describe where on the overlay image buttons can be found for each overlay. E.g.: overlay0_descs = 3 # Three buttons for this overlay in total overlay0_desc0 = "a,32,64,radial,10,20" overlay0_desc1 = "start,100,50,rect,80,10" overlay0_desc2 = "overlay_next,200,180,radial,40,40" The format is: "button,position_x,position_y,hitbox_type,range_x,range_y" button corresponds to the input event being generated. The names are the same as in the general input config, e.g. input_player1_start would translate to start here. If button is a keyboard key, it must be prefixed with retrok_, e.g. retrok_a. overlay_next is a special bind designed to swap to the next overlay, or wrap around to the first one. Button nul means no input. For an up-to-date view of what buttons are called, check the input_config_bind_map variable in: [https://github.com/libretro/RetroArch/blob/master/configuration.c](https://github.com/libretro/RetroArch/blob/master/configuration.c). For an up-to-date view of what keyboard keys are called, check the input_config_key_map variable in: [https://github.com/libretro/RetroArch/blob/master/input/input_keymaps.c](https://github.com/libretro/RetroArch/blob/master/input/input_keymaps.c). position_x and position_y are the x and y coordinates in pixels of the source image for the center of the button. It is possible to use normalized coordinates as well. This is necessary when a full-screen overlay is not used. overlay0_desc0_normalized = true will force normalized coordinates. overlay0_normalized = true sets all descriptors to true unless overridden specifically. hitbox_type describes which type of shape the button has. radial (circle, ellipse) and rect (rectangular) shapes are supported. range_x and range_y describe the size of the button. The semantics differ slightly for radial and rect hitbox types. For radial shape, range_x and range_y describe the radius in x and y directions in pixels of the source image. For rect shape, the range_x and range_y values represent the distance from center to the edge of the rect in terms of pixels of the source image. E.g. a range_x of 20 would mean the width of the rectangular is 40 pixels in total. ## Special button types A few buttons are not listed in input_config_bind_map: analog_left, analog_right, dpad_area, and abxy_area. analog_left and analog_right translate to analog sticks. These buttons must have hitbox type radial. It is possible to configure where saturation kicks in using overlay%u_desc%u_saturate_pct. E.g. a value of 0.75 means the 75% inner part contains the entire analog range. Outside the 75% it will be fully saturated. dpad_area and abxy_area are 8-way areas whose input events are based on the direction pressed, i.e. angle from hitbox center. An 8-way area can be used as-is or redefined. E.g. this creates a d-pad consisting of analog directions, and a face button diamond consisting of A,B,R,L: overlay0_desc0 = "dpad_area,0.15,0.57,rect,0.1094,0.1944" overlay0_desc0_up = r_y_minus overlay0_desc0_down = r_y_plus overlay0_desc0_left = r_x_minus overlay0_desc0_right = r_x_plus overlay0_desc1 = "abxy_area,0.85,0.57,rect,0.1607,0.2857" overlay0_desc1_up = r overlay0_desc1_left = l ## Using per-button overlays It is possible to use individual overlays per button. The given image will be displayed with same size as the hitbox in the input descriptor. overlay0_desc0_overlay = button.png ## Let overlay buttons move around when pressed For especially overlay buttons which map to analogs, it is useful to allow an image to follow the movement of the finger. To enable an overlay to follow the finger movement within its bounding area use the movable attribute: overlay0_desc0_overlay = analog.png # Need some per-descriptor overlay overlay0_desc0_movable = true # Overlay image will now move around ## Let buttons light up when they are pressed When using individial overlays per button it will make sense to have buttons light up when they are pressed. To do this, the alpha value per-button will be multiplied by a factor. overlay0_desc0_alpha_mod = 2.0 # Alpha is multiplied 2x when pressed. To set a default across all descriptors for an overlay, you can do so: overlay0_alpha_mod = 2.0 ## Adjust a button's hitbox A button's hitbox can be adjusted without affecting its image, input center, or analog saturation. Use reach_x/y to multiply hitbox width/height symmetrically. Use reach_up/down/left/right to multiply hitbox range in that direction. E.g. this creates a d-pad and extends its hitbox vertically by 60%, and left by 40%: overlay0_desc0 = "dpad_area,0.15,0.57,rect,0.1094,0.1944" overlay0_desc0_reach_y = 1.6 # Multiply hitbox height overlay0_desc0_reach_left = 1.4 # Multiply hitbox width on left side ![Hitbox reach](../../../image/retroarch/overlays/hitbox_reach.png) Setting reach_x or reach_y to 0 removes the hitbox. The button then can't be pressed, but it will still light up if another button creates the same input. This is useful for animating a dpad_area or abxy_area. ## Let buttons have bigger hitbox when they are pressed When pressed, you can make the hitboxes larger while the button is pressed: overlay0_desc0_range_mod = 1.5 # For the particular descriptor overlay0_range_mod = 1.5 # Default for all descriptors ## Handling hitbox overlap Avoid unwanted overlap by making a button exclusive and/or range_mod_exclusive. An exclusive button blocks other buttons pressed by the same finger. A range_mod_exclusive button blocks with higher priority, but only when range_mod is in effect, i.e. one poll after it is pressed. E.g. this overlaps an analog stick and a d-pad. The analog is exclusive, so initially it owns the overlapped hitbox area. Both buttons are range_mod_exclusive, so the one controlled first owns its range_mod extended hitbox area. overlay0_desc0 = "dpad_area,0.15,0.57,rect,0.1094,0.1944" overlay0_desc0_reach_x = 2.08 overlay0_desc0_reach_up = 1.62 overlay0_desc0_reach_down = 1.96 overlay0_desc0_range_mod = 1.2 overlay0_desc0_range_mod_exclusive = true # Give dpad_area priority if controlled first overlay0_desc1 = "analog_left,0.31,0.81,radial,0.0964,0.1928" overlay0_desc1_exclusive = true # Give analog_left priority on first touch overlay0_desc1_range_mod = 2.75 overlay0_desc1_range_mod_exclusive = true # Give analog_left priority if controlled first ![Hitbox exclusive](../../../image/retroarch/overlays/exclusive_hitbox.png) ![Hitbox range_mod_exclusive 1](../../../image/retroarch/overlays/range_mod_exclusive1.png) ![Hitbox range_mod_exclusive 2](../../../image/retroarch/overlays/range_mod_exclusive2.png) ## Triggering multiple buttons with one desc It's possible to trigger multiple buttons (e.g. diagonals) with one overlay desc. overlay0_desc0 = "left|up,32,64,radial,10,20" will trigger both left and up at same time. Keyboard keys are an exception; an overlay desc can have only one key. ## Go to arbitrary overlay index To build some kind of menu system, one would need the ability for overlay_next to refer to any overlay. To do this, two extra things must be configured: overlay2_overlay = "some_overlay.png" overlay2_name = "overview_overlay" # A name which can be referred to. Must be set if it is to be refered to. overlay0_desc0 = "overlay_next,200,180,radial,40,40" overlay0_desc0_next_target = "overview_overlay" # When this overlay_next is pressed, it will go to index 2 directly, instead of the default 1. ================================================ FILE: docs/development/retroarch/input/parallel-port-controllers.md ================================================ # Parallel port controllers ## Linux parport controller driver RetroArch supports parallel port controllers on Linux via the "parport" controller driver. It uses an extended version of the Linux Multisystem 2-button joystick protocol. | Function | Pin | Register | Bit | Active | |----------|-----|----------|-----|--------| | Up | 2 | Data | 0 | Low | | Down | 3 | Data | 1 | Low | | Left| 4 | Data | 2 | Low | | Right| 5 | Data | 3 | Low | | A | 6 | Data | 4 | Low | | B | 7 | Data | 5 | Low | | Start | 8 | Data | 6 | Low | | Select | 9 | Data | 7 | Low | | Menu toggle | 10 | Status | 6 | Low | | X | 11 | Status | 7 | Low* | | Y | 12 | Status | 5 | Low | | L1 | 13 | Status | 4 | Low | | R1 | 15 | Status | 3 | Low | (*) Pin is hardware inverted, but RetroArch inverts it back again so the same pullup scheme may be used for all pins. Pin 1 is set high so it can be used for pullups. RetroArch does not perform debouncing, and so long as the button settling time is less than the frame time no bouncing will be observed. This replicates the latching behavior common in old games consoles. For optimum latency and jitter a high performance debouncing routine should be implemented in the controller hardware. Parallel port hardware does not provide a way to detect non-connected pins. To avoid rendering the menu usable with spurious button presses, RetroArch checks each pin on startup and assumes any active pin is not connected. Avoid holding controller buttons while starting RetroArch or those buttons will be disabled. ================================================ FILE: docs/development/retroarch/netplay.md ================================================ # Netplay RetroArch allows a second (or further) player, or spectators, to be connected via the Internet. RetroArch's netplay code is based on replay, and provides netplay over unreliable networks free of input latency in the default configuration. Netplay supports up to 16 players and many spectators. Netplay in RetroArch is guaranteed¹ to work with perfect synchronization given a few minor constraints: 1. The core is deterministic, 2. The only input devices the core interacts with are the gamepad and analog sticks, and 3. Both the core and the loaded content are identical on host and client. Cores are expected to support serialization for proper netplay behavior, but netplay will work in limited fashion with cores that do not support serialization. The experience will be far more smooth with serialization. Netplay in RetroArch works by expecting input to come delayed from the network, then rewinding and re-playing with the delayed input to get a consistent state. At any given time, all netplay clients may be in inconsistent states, but once they receive each other's delayed data, they invisibly rewind to the last time they were consistent, replay with the new input, and reach a new state, notionally closer to the "correct", canonical state than the previous one. So long as both sides agree on which frame is which, it should be impossible for them to become de-synced, since each input event always happens at the correct frame. ¹ Guarantee not actually a guarantee. ## Behavior Netplay's protocol uses TCP, as reliability and in-order delivery are both mandatory for correct behavior. A single netplay server may have connections from multiple netplay clients. For most behavior, the server and client are equal participants, but for operations which require global synchronization, the server is canonical. In normal, running behavior, each playing client simply sends the input state of their controller every frame, and the server forwards input data between clients. Every client and the server is aware of which player slots are in use (i.e., which controllers are plugged in), and the server is aware of which client corresponds to which player slot. It is crucial that every player send their input data in order for every frame, and thus every client keeps in mind the frame counter for every player. If input data is received with an unexpectedly low frame number, it is ignored, and if input data is received with an unexpectedly high frame number, the connection is terminated. It is also crucial that every player agree on which frame is which, and so during initial connection the server gives a canonical frame count and a serialized save state, allowing the client to join mid-stream. Spectators send no input data. When new input data is received from a player, if it is before the currently executing frame, RetroArch will invisibly rewind and replay with the new input data, arriving at the original frame so that the local player's own input is always seemless. A typical, playing client sends no data other than its own input every frame. During normal play, the server sends its own input data. If the server is not playing, but spectating, it sends a special "no input" packet, so that clients may nonetheless no its frame count. Other spectators send no data. Other events coordinate on the server's frame counter, and most may therefore only be performed by the server. For instance, for a client to switch from spectating to playing, it cannot simply start sending input data, but must send a request to change modes, which the server will honor at its present frame count. The client may have to rewind to send data from earlier frames, or wait to send input data until its local frame count has reached the server's. In particular, resets and savestate loads are always synchronized to the server's frame count, and thus only the server may reset the core or load a savestate. Because input preceeding a savestate load is irrelevant, upon receiving a savestate load command, all frame counts are updated to be at least the server's frame count, including the local frame count if applicable. This is the only condition under which the frame count will skip at a rate greater than one frame per executed frame. ## Implementation Netplay is in effect a buffer of input states (implemented as a ring of buffers) and some pre- and post-frame behaviors. There are three important locations, each of which : self, other and unread. Each refers to a frame, and a state buffer corresponding to that frame. The state buffer contains the savestate for the frame, and the input from both the local and remote players. Self is where RetroArch believes itself to be, which may be ahead or behind of what it's read from the peer. Self progresses at a rate of one frame per executed frame, except when the local frame count is forced to skip ahead due to loading a state. Unread is the first frame at which not all players' data has been read. Typically unread is less than self, but it is possible for one client to get ahead of others. Other is where it was most recently in perfect sync: i.e., other-1 is the last frame from which all local and remote input have been actioned. It is never necessary to rewind farther than other in order to attain synchronization, and other is always less than or equal to both self and unread. Since the state buffer is a ring, other is the first frame that it's unsafe to overwrite. The server has a slightly more complicated job as it can handle multiple clients, however it is not vastly more complicated: For each connection which is playing (i.e., has a controller), it maintains a per-player unread frame, and the global unread frame is the earliest of each player unread frame. The server forwards input data: When input data is received from an earlier frame than the server's current frame, it forwards it immediately. Otherwise, it forwards it when the frame is reached. i.e., during frame n, the server may send its own and any number of other players' data for frame n, but will never send frame n+1. This is because the server's clock is the arbiter of all synchronization-related events, such as flipping players, players joining and parting, and saving/loading states. Pre-frame, netplay serializes the core's state, polls for local input, and polls for input from the network. If the input from the network is too far behind (i.e., unread is too far behind self), it stalls to allow the other side to catch up. To assure that this stalling does not block the UI thread, it is implemented similarly to pausing, rather than by blocking on the socket. If input has not been received for the other side up to the current frame (the usual case), the remote input is simulated in a simplistic manner. Each frame's local serialized state and simulated or real input goes into the frame buffers. During the frame of execution, when the core requests input, it receives the input from the state buffer, both local and real or simulated remote. Post-frame, it checks whether it's read more than it's actioned, i.e. If read > other and self > other. If so, it first checks whether its simulated remote data was correct. If it was, it simply moves other up. If not, it rewinds to other (by loading the serialized state there) and runs the core in replay mode with the real data up to the least of self and read, then sets other to that. To avoid latency building up, if the input from the network is too far ahead (i.e., unread is too far ahead of self), the frame limiter is momentarily disabled to catch up. Note that since network latency is expected, the normal case is the opposite: unread is behind self. When in netplay mode, the callback for receiving input is replaced by input_state_net. It is the role of input_state_net to combine the true local input (whether live or replay) with the remote input (whether true or simulated). Some thoughts about "frame counts": The frame counters act like indexes into a 0-indexed array; i.e., they refer to the first unactioned frame. So, when read_frame_count is 23, we've read 23 frames, but the last frame we read is frame 22. With self_frame_count it's slightly more complicated, since there are two relevant actions: Reading the data and emulating with the data. The frame count is only incremented after the latter, so there is a period of time during which we've actually read self_frame_count+1 frames of local input. Clients may come and go, and may start or stop playing even as they're connected. A client that is not playing is said to be spectating: It receives all the same data but sends none. A client may switch from spectating to playing by sending the appropriate request, at which point it is allotted a player number (see the SPECTATE, PLAY and MODE commands below). The server may also be in spectator mode, but as the server never sends data early (i.e., it only forwards data on the frame it's reached), it must also inform all clients of its own current frame even if it has no input. The NOINPUT command is provided for that purpose. ## Protocol A netplay connection involves a handshake, which assures that client and server are running the same software and brings the client to synchronization, and then an exchange of input packets. The handshake procedure (this part is done by both server and client): 1. Send connection header 2. Receive and verify connection header 3. Send nickname 4. Receive nickname For the client: 5. Send PASSWORD if applicable 4. Receive INFO 5. Send INFO 6. Receive SYNC For the server: 5. Receive PASSWORD if applicable 6. Send INFO 7. Receive INFO 8. Send SYNC Note that both the server and the client send the connection header before reading it. This is intentional. It allows either servers or clients (but not both) to generalize, by echoing the connection header of the other side. ## Other features Typically, it is assumed that input latency is not desired. However, input latency is an option. The benefit of input latency is that the actual execution lags behind one's frame count, and thus it is more usual that remote data is available, and rewinding is both less frequent and less expensive. There is an additional location in the state buffer, run, used when input latency is enabled. In that case, self points to where input is being read, and run points to the frame actually being executed. Run is purely local. ## Command format Netplay commands consist of a 32-bit command identifier, followed by a 32-bit payload size, both in network byte order, followed by a payload. The command identifiers are listed in netplay.h. The commands are described below. Unless specified otherwise, all payload values are in network byte order. **Command**: ACK Payload: None Description: > Acknowledgement. Not used. **Command**: NAK Payload: None Description: > Negative Acknowledgement. If received, the connection is terminated. Sent > whenever a command is malformed or otherwise not understood. **Command**: DISCONNECT Payload: None Description: > Gracefully disconnect. Not used. **Command**: INPUT Payload: { frame number: uint32 is server data: 1 bit player: 31 bits controller input: uint32 analog 1 input: uint32 analog 2 input: uint32 } Description: > Input state for each frame. Netplay must send an INPUT command for every > frame in order to function at all. Client's player value is ignored. Server > indicates which frames are its own input data because INPUT is a > synchronization point: No synchronization events from the given frame may > arrive after the server's input for the frame. **Command**: NOINPUT Payload: { frame number: uint32 } Description: > Sent by the server to indicate a frame has passed when the server is not > otherwise sending data. **Command**: NICK Payload: { nickname: char[32] } Description: > Send nickname. Mandatory handshake command. **Command**: PASSWORD Payload: { password hash: char[64] } Description: > Send hashed password to server. Mandatory handshake command for clients if > the server demands a password. **Command**: INFO Payload { core name: char[32] core version: char[32] content CRC: uint32 } Description: > Send core/content info. Mandatory handshake command. Sent by server first, > then by client, and must match. Server may send INFO with no payload, in > which case the client sends its own info and expects the server to load the > appropriate core and content then send a new INFO command. If mutual > agreement cannot be achieved, the correct solution is to simply disconnect. **Command**: SYNC Payload: { frame number: uint32 paused?: 1 bit connected players: 31 bits flip frame: uint32 controller devices: uint32[16] client nick: char[32] sram: variable } Description: > Initial state synchronization. Mandatory handshake command from server to > client only. Connected players is a bitmap with the lowest bit being player > 0. Flip frame is 0 if players aren't flipped. Controller devices are the > devices plugged into each controller port, and 16 is really MAX_USERS. > Client is forced to have a different nick if multiple clients have the same > nick. **Command**: SPECTATE Payload: None Description: > Request to enter spectate mode. The client should immediately consider itself > to be in spectator mode and send no further input. **Command**: PLAY Payload: { reserved: 31 bits as slave?: 1 bit } Description: > Request to enter player mode. The client must wait for a MODE command before > sending input. Server may refuse or force slave connections, so the request > is not necessarily honored. Payload may be elided if zero. **Command**: MODE Payload: { frame number: uint32 reserved: 13 bits slave: 1 bit playing: 1 bit you: 1 bit player number: uint16 } Description: > Inform of a connection mode change (possibly of the receiving client). Only > server-to-client. Frame number is the first frame in which player data is > expected, or the first frame in which player data is not expected. In the > case of new players the frame number must be later than the last frame of the > server's own input that has been sent, and in the case of leaving players the > frame number must be later than the last frame of the relevant player's input > that has been transmitted. **Command**: MODE_REFUSED Payload: { reason: uint32 } Description: > Inform a client that its request to change modes has been refused. **Command**: CRC Payload: { frame number: uint32 hash: uint32 } Description: > Informs the peer of the correct CRC hash for the specified frame. If the > receiver's hash doesn't match, they should send a REQUEST_SAVESTATE command. **Command**: REQUEST_SAVESTATE Payload: None Description: Requests that the peer send a savestate. **Command**: LOAD_SAVESTATE Payload: { frame number: uint32 uncompressed size: uint32 serialized save state: blob (variable size) } Description: > Cause the other side to load a savestate, notionally one which the sending > side has also loaded. If both sides support zlib compression, the serialized > state is zlib compressed. Otherwise it is uncompressed. **Command**: PAUSE Payload: { nickname: char[32] } Description: > Indicates that the core is paused. The receiving peer should also pause. The > server should pass it on, using the known correct name rather than the > provided name. **Command**: RESUME Payload: None Description: > Indicates that the core is no longer paused. **Command**: STALL Payload: { frames: uint32 } Description: > Request that a client stall for the given number of frames. **Command**: RESET Payload: { frame number: uint32 } Description: > Indicate that the core was reset at the beginning of the given frame. **Command**: CHEATS Unused **Command**: FLIP_PLAYERS Payload: { frame number: uint32 } Description: > Flip players at the requested frame. **Command**: CFG Unused **Command**: CFG_ACK Unused ================================================ FILE: docs/development/retroarch/network-control-interface.md ================================================ # RetroArch Network Control Interface RetroArch exposes a UDP-based Network Control Interface (NCI) that allows remote control of a running instance. Commands can be sent from the command line, scripts, or any program capable of sending UDP packets. ## Enabling the Interface Enable the NCI through RetroArch settings: - **`network_cmd_enable`** - Set to `true` to enable the network command interface - **`network_cmd_port`** - UDP port to listen on (default: `55355`) These can be set in `retroarch.cfg`: ```ini network_cmd_enable = "true" network_cmd_port = "55355" ``` Or via the menu: Settings > Network > Network Commands. ## Sending Commands Use the `--command` CLI flag to send a command to a running RetroArch instance: ```bash retroarch --command "COMMAND;HOST;PORT" ``` - `HOST` and `PORT` are optional - `retroarch --command "COMMAND;HOST"` uses the default port (`55355`) - `retroarch --command "COMMAND"` uses `localhost` and the default port Since the interface uses plain UDP packets, you can also send commands with `nc` (netcat), which is available on both Linux and macOS: ```bash echo -n "COMMAND" | nc -u -w1 localhost 55355 ``` The `-w1` flag tells `nc` to wait up to 1 second, which is enough time to receive a response from commands that return one. The response is sent back to the sender's address automatically. ## Action Commands Action commands accept arguments and may return responses over UDP. ### VERSION Returns the RetroArch version string. - **Arguments:** None - **Response:** Version string (e.g., `1.19.1`) ```bash retroarch --command "VERSION" ``` ### GET_STATUS Returns the current emulation status. - **Arguments:** None - **Response:** `GET_STATUS PAUSED|PLAYING system_id,game_basename,crc32=XXXXXXXX` when content is loaded, or `GET_STATUS CONTENTLESS` when no content is running ```bash retroarch --command "GET_STATUS" ``` ### GET_CONFIG_PARAM Queries a configuration parameter value. - **Arguments:** `` - **Response:** `GET_CONFIG_PARAM ` - **Supported parameters:** - `video_fullscreen` - Whether fullscreen is active (`true`/`false`) - `savefile_directory` - Save file directory path - `savestate_directory` - Save state directory path - `runtime_log_directory` - Runtime log directory path - `log_dir` - Log directory path - `cache_directory` - Cache directory path - `system_directory` - System/BIOS directory path - `netplay_nickname` - Current netplay username - `active_replay` - Active replay info as `identifier flags frame_counter` (requires BSV movie support) ```bash retroarch --command "GET_CONFIG_PARAM savefile_directory" ``` ### SHOW_MSG Displays an on-screen display (OSD) message. - **Arguments:** `` ```bash retroarch --command "SHOW_MSG Game saved successfully" ``` ### SET_SHADER Loads a shader preset by file path. Requires shader support (CG, GLSL, Slang, or HLSL). - **Arguments:** `` ```bash retroarch --command "SET_SHADER /path/to/shader.glslp" ``` ### READ_CORE_RAM Reads bytes from core memory using achievement addresses. Requires achievements (CHEEVOS) support. Prefer `READ_CORE_MEMORY` for system addresses. - **Arguments:** `
` (address in hexadecimal) - **Response:** `READ_CORE_RAM
...` (bytes as hex), or `READ_CORE_RAM
-1` on failure ```bash retroarch --command "READ_CORE_RAM 1000 16" ``` ### WRITE_CORE_RAM Writes bytes to core memory using achievement addresses. Requires achievements (CHEEVOS) support. Disables achievements hardcore mode. Prefer `WRITE_CORE_MEMORY` for system addresses. - **Arguments:** `
...` (address and bytes in hexadecimal) ```bash retroarch --command "WRITE_CORE_RAM 1000 FF 00 AB" ``` ### READ_CORE_MEMORY Reads bytes from core memory using the system memory map. - **Arguments:** `
` (address in hexadecimal) - **Response:** `READ_CORE_MEMORY
...` (bytes as hex), or `READ_CORE_MEMORY
-1 ` on failure - **Error messages:** `no memory map defined`, `no descriptor for address`, `no data for descriptor` ```bash retroarch --command "READ_CORE_MEMORY 8000 32" ``` ### WRITE_CORE_MEMORY Writes bytes to core memory using the system memory map. Disables achievements hardcore mode if active. - **Arguments:** `
...` (address and bytes in hexadecimal) - **Response:** `WRITE_CORE_MEMORY
` on success, or `WRITE_CORE_MEMORY
-1 ` on failure - **Error messages:** `no memory map defined`, `no descriptor for address`, `no data for descriptor`, `descriptor data is readonly` ```bash retroarch --command "WRITE_CORE_MEMORY 8000 FF 00 AB" ``` ### LOAD_STATE_SLOT Loads a save state from a specific slot number. - **Arguments:** `` - **Response:** `LOAD_STATE_SLOT ` ```bash retroarch --command "LOAD_STATE_SLOT 3" ``` ### PLAY_REPLAY_SLOT Starts playback of a replay from a specific slot. Requires BSV movie support. - **Arguments:** `` - **Response:** `PLAY_REPLAY_SLOT ` ```bash retroarch --command "PLAY_REPLAY_SLOT 1" ``` ### SEEK_REPLAY Seeks to a specific frame in the currently active replay. Requires BSV movie support. Disabled during achievements hardcore mode. - **Arguments:** `` - **Response:** `OK ` on success, or `NO` on failure ```bash retroarch --command "SEEK_REPLAY 5000" ``` ### SAVE_FILES Saves all save files (SRAM) to disk. - **Arguments:** None - **Response:** `OK` on success, `NO` on failure ```bash retroarch --command "SAVE_FILES" ``` ### LOAD_FILES Loads all save files (SRAM) from disk. - **Arguments:** None - **Response:** `OK` on success, `NO` on failure ```bash retroarch --command "LOAD_FILES" ``` ### LOAD_CORE Loads a libretro core from a file path. - **Arguments:** `` ```bash retroarch --command "LOAD_CORE /path/to/core_libretro.so" ``` ## State/Button Commands State commands simulate input presses and take no arguments. They trigger the same actions as pressing the corresponding hotkey. ### Menu Navigation Navigate the RetroArch menu remotely. #### MENU_TOGGLE Open or close the menu. - **Arguments:** None ```bash retroarch --command "MENU_TOGGLE" ``` #### MENU_UP Navigate up in the menu. - **Arguments:** None ```bash retroarch --command "MENU_UP" ``` #### MENU_DOWN Navigate down in the menu. - **Arguments:** None ```bash retroarch --command "MENU_DOWN" ``` #### MENU_LEFT Navigate left in the menu. - **Arguments:** None ```bash retroarch --command "MENU_LEFT" ``` #### MENU_RIGHT Navigate right in the menu. - **Arguments:** None ```bash retroarch --command "MENU_RIGHT" ``` #### MENU_A Menu confirm/accept. - **Arguments:** None ```bash retroarch --command "MENU_A" ``` #### MENU_B Menu back/cancel. - **Arguments:** None ```bash retroarch --command "MENU_B" ``` ### Game Control Control game execution state. #### QUIT Quit RetroArch. - **Arguments:** None ```bash retroarch --command "QUIT" ``` #### CLOSE_CONTENT Close the currently running content. - **Arguments:** None ```bash retroarch --command "CLOSE_CONTENT" ``` #### RESET Reset the current game. - **Arguments:** None ```bash retroarch --command "RESET" ``` #### PAUSE_TOGGLE Toggle pause. - **Arguments:** None ```bash retroarch --command "PAUSE_TOGGLE" ``` #### FRAMEADVANCE Advance one frame while paused. - **Arguments:** None ```bash retroarch --command "FRAMEADVANCE" ``` ### Speed Control Adjust emulation speed. #### FAST_FORWARD Toggle fast forward. - **Arguments:** None ```bash retroarch --command "FAST_FORWARD" ``` #### FAST_FORWARD_HOLD Hold fast forward (active while held). - **Arguments:** None ```bash retroarch --command "FAST_FORWARD_HOLD" ``` #### SLOWMOTION Toggle slow motion. - **Arguments:** None ```bash retroarch --command "SLOWMOTION" ``` #### SLOWMOTION_HOLD Hold slow motion (active while held). - **Arguments:** None ```bash retroarch --command "SLOWMOTION_HOLD" ``` #### REWIND Rewind gameplay. - **Arguments:** None ```bash retroarch --command "REWIND" ``` ### Audio Control audio settings. #### MUTE Toggle audio mute. - **Arguments:** None ```bash retroarch --command "MUTE" ``` #### VOLUME_UP Increase audio volume. - **Arguments:** None ```bash retroarch --command "VOLUME_UP" ``` #### VOLUME_DOWN Decrease audio volume. - **Arguments:** None ```bash retroarch --command "VOLUME_DOWN" ``` ### Save States Manage save states via hotkey simulation. #### LOAD_STATE Load save state from the current slot. - **Arguments:** None ```bash retroarch --command "LOAD_STATE" ``` #### SAVE_STATE Save state to the current slot. - **Arguments:** None ```bash retroarch --command "SAVE_STATE" ``` #### STATE_SLOT_PLUS Increment the save state slot. - **Arguments:** None ```bash retroarch --command "STATE_SLOT_PLUS" ``` #### STATE_SLOT_MINUS Decrement the save state slot. - **Arguments:** None ```bash retroarch --command "STATE_SLOT_MINUS" ``` ### Replays Control replay recording and playback. #### PLAY_REPLAY Start replay playback. - **Arguments:** None ```bash retroarch --command "PLAY_REPLAY" ``` #### RECORD_REPLAY Start replay recording. - **Arguments:** None ```bash retroarch --command "RECORD_REPLAY" ``` #### HALT_REPLAY Stop the current replay. - **Arguments:** None ```bash retroarch --command "HALT_REPLAY" ``` #### SAVE_REPLAY_CHECKPOINT Save a checkpoint during replay. - **Arguments:** None ```bash retroarch --command "SAVE_REPLAY_CHECKPOINT" ``` #### PREV_REPLAY_CHECKPOINT Go to the previous replay checkpoint. - **Arguments:** None ```bash retroarch --command "PREV_REPLAY_CHECKPOINT" ``` #### NEXT_REPLAY_CHECKPOINT Go to the next replay checkpoint. - **Arguments:** None ```bash retroarch --command "NEXT_REPLAY_CHECKPOINT" ``` #### REPLAY_SLOT_PLUS Increment the replay slot. - **Arguments:** None ```bash retroarch --command "REPLAY_SLOT_PLUS" ``` #### REPLAY_SLOT_MINUS Decrement the replay slot. - **Arguments:** None ```bash retroarch --command "REPLAY_SLOT_MINUS" ``` ### Disk Control Manage multi-disk games. #### DISK_EJECT_TOGGLE Toggle disk tray eject. - **Arguments:** None ```bash retroarch --command "DISK_EJECT_TOGGLE" ``` #### DISK_NEXT Switch to next disk. - **Arguments:** None ```bash retroarch --command "DISK_NEXT" ``` #### DISK_PREV Switch to previous disk. - **Arguments:** None ```bash retroarch --command "DISK_PREV" ``` ### Shaders Control shader settings. #### SHADER_TOGGLE Toggle shaders on/off. - **Arguments:** None ```bash retroarch --command "SHADER_TOGGLE" ``` #### SHADER_HOLD Hold shader (active while held). - **Arguments:** None ```bash retroarch --command "SHADER_HOLD" ``` #### SHADER_NEXT Switch to next shader preset. - **Arguments:** None ```bash retroarch --command "SHADER_NEXT" ``` #### SHADER_PREV Switch to previous shader preset. - **Arguments:** None ```bash retroarch --command "SHADER_PREV" ``` ### Cheats Manage cheat codes. #### CHEAT_TOGGLE Toggle the current cheat on/off. - **Arguments:** None ```bash retroarch --command "CHEAT_TOGGLE" ``` #### CHEAT_INDEX_PLUS Select the next cheat. - **Arguments:** None ```bash retroarch --command "CHEAT_INDEX_PLUS" ``` #### CHEAT_INDEX_MINUS Select the previous cheat. - **Arguments:** None ```bash retroarch --command "CHEAT_INDEX_MINUS" ``` ### Recording and Screenshots Capture gameplay. #### SCREENSHOT Take a screenshot. - **Arguments:** None ```bash retroarch --command "SCREENSHOT" ``` #### RECORDING_TOGGLE Toggle video recording. - **Arguments:** None ```bash retroarch --command "RECORDING_TOGGLE" ``` #### STREAMING_TOGGLE Toggle video streaming. - **Arguments:** None ```bash retroarch --command "STREAMING_TOGGLE" ``` ### Display and UI Control display and interface settings. #### TURBO_FIRE_TOGGLE Toggle turbo fire mode. - **Arguments:** None ```bash retroarch --command "TURBO_FIRE_TOGGLE" ``` #### GRAB_MOUSE_TOGGLE Toggle mouse grab. - **Arguments:** None ```bash retroarch --command "GRAB_MOUSE_TOGGLE" ``` #### GAME_FOCUS_TOGGLE Toggle game focus mode. - **Arguments:** None ```bash retroarch --command "GAME_FOCUS_TOGGLE" ``` #### FULLSCREEN_TOGGLE Toggle fullscreen mode. - **Arguments:** None ```bash retroarch --command "FULLSCREEN_TOGGLE" ``` #### UI_COMPANION_TOGGLE Toggle the UI companion window. - **Arguments:** None ```bash retroarch --command "UI_COMPANION_TOGGLE" ``` ### Performance Toggle performance-related features. #### VRR_RUNLOOP_TOGGLE Toggle variable refresh rate runloop. - **Arguments:** None ```bash retroarch --command "VRR_RUNLOOP_TOGGLE" ``` #### RUNAHEAD_TOGGLE Toggle run-ahead latency reduction. - **Arguments:** None ```bash retroarch --command "RUNAHEAD_TOGGLE" ``` #### PREEMPT_TOGGLE Toggle preemptive frames. - **Arguments:** None ```bash retroarch --command "PREEMPT_TOGGLE" ``` #### FPS_TOGGLE Toggle FPS display. - **Arguments:** None ```bash retroarch --command "FPS_TOGGLE" ``` #### STATISTICS_TOGGLE Toggle onscreen statistics. - **Arguments:** None ```bash retroarch --command "STATISTICS_TOGGLE" ``` #### AI_SERVICE Trigger the AI service. - **Arguments:** None ```bash retroarch --command "AI_SERVICE" ``` ### Netplay Control netplay features. #### NETPLAY_PING_TOGGLE Toggle netplay ping display. - **Arguments:** None ```bash retroarch --command "NETPLAY_PING_TOGGLE" ``` #### NETPLAY_HOST_TOGGLE Toggle netplay hosting. - **Arguments:** None ```bash retroarch --command "NETPLAY_HOST_TOGGLE" ``` #### NETPLAY_GAME_WATCH Toggle between playing and spectating. - **Arguments:** None ```bash retroarch --command "NETPLAY_GAME_WATCH" ``` #### NETPLAY_PLAYER_CHAT Open the netplay chat. - **Arguments:** None ```bash retroarch --command "NETPLAY_PLAYER_CHAT" ``` #### NETPLAY_FADE_CHAT_TOGGLE Toggle chat fade behavior. - **Arguments:** None ```bash retroarch --command "NETPLAY_FADE_CHAT_TOGGLE" ``` ### Overlay Control on-screen overlays. #### OVERLAY_NEXT Switch to the next overlay. - **Arguments:** None ```bash retroarch --command "OVERLAY_NEXT" ``` #### OSK Toggle the on-screen keyboard. - **Arguments:** None ```bash retroarch --command "OSK" ``` ================================================ FILE: docs/development/retroarch/new-menu-options.md ================================================ # Adding a RetroArch menu option The RetroArch menu system is a bit complex as no UI framework is used for implementing it, due to extreme portability reasons. This guide outlines adding one setting to RetroArch global configuration and the corresponding menu entry, but you may encounter special menus or more complex settings. Try to add the new bits to places where they can be logically found. ## Files you need to change * `msg_hash_us.h` * `msg_hash_lbl.h` * `msg_hash.h` * `menu_cbs_sublabel.c` * `menu_setting.c` * `menu_displaylist.c` * `configuration.c` * `configuration.h` * `config.def.h` * `ui/drivers/qt/qt_options.cpp` ## Creating the config variable For this example the variable will be a boolean option for showing messages about failed autoconfig. You can also view the pull request [here](https://github.com/libretro/RetroArch/pull/17636/files). 1. Open `config.def.h` 2. Add `#define DEFAULT_NOTIFICATION_SHOW_AUTOCONFIG_FAILS true` to provide a generic default for the option. If needed, use compiler switches for different defaults on different platforms. 3. Open `configuration.h` 4. There are sections for each variable type(string, float, int, uint and bool) go to `bools` and add `bool notification_show_autoconfig_fails;` 5. Open `configuration.c` 6. Add `SETTING_BOOL("notification_show_autoconfig_fails", &settings->bools.notification_show_autoconfig_fails, true, DEFAULT_NOTIFICATION_SHOW_AUTOCONFIG_FAILS, false);` to `populate_settings_bool`. The variable is now part of global RetroArch settings, will be saved/loaded from configuration file and can be used from RetroArch code, but the menu still doesn't know it exists. ## Defining menu labels and messages Time to define the labels for identifying and displaying the new setting. 1. Open `msg_hash.h` 2. Add `MENU_LABEL(NOTIFICATION_SHOW_AUTOCONFIG_FAILS)` to `enum msg_hash_enums` 3. Open `intl/msg_hash_lbl.h` 4. Add `MSG_HASH( MENU_ENUM_LABEL_NOTIFICATION_SHOW_AUTOCONFIG_FAILS, "notification_show_autoconfig_fails")` in the `MENU_ENUM_LABEL_` section. This identifier may appear in logs, but not in the menu. 5. Open `intl/msg_hash_us.h` 6. Add `MSG_HASH( MENU_ENUM_LABEL_VALUE_NOTIFICATION_SHOW_AUTOCONFIG_FAILS, "Input (Autoconfig) Failure Notifications")` in the `MENU_ENUM_LABEL_VALUE_` section. This is what the user and the translators actually see. 7. Add `MSG_HASH( MENU_ENUM_SUBLABEL_NOTIFICATION_SHOW_AUTOCONFIG_FAILS, "Display an on-screen message when input devices could not be configured.")` section. Sublabels are a bit more detailed explanations that appear underneath the menu item. The option is now defined but the menu has still not been told to display it. ## Displaying your option Now the menu has to be told how to display the option. 1. Open `menu/cbs/menu_cbs_sublabel.c` 2. Add `DEFAULT_SUBLABEL_MACRO( action_bind_sublabel_notification_show_autoconfig_fails, MENU_ENUM_SUBLABEL_NOTIFICATION_SHOW_AUTOCONFIG_FAILS)` to the block of `DEFAULT_SUBLABEL_MACRO` functions. 3. Add `case MENU_ENUM_LABEL_NOTIFICATION_SHOW_AUTOCONFIG_FAILS: BIND_ACTION_SUBLABEL(cbs, action_bind_sublabel_notification_show_autoconfig_fails); break;` to the `menu_cbs_init_bind_sublabel` function. 4. Open `menu/menu_setting.c` 5. Find your variables section(saving, netplay, video, ...) and add `CONFIG_BOOL` macro. The options are too numerous to list here, look for a similar example to what you plan to add. This entry controls the related setting, the menu labels, and possible actions. Simple config types already have implemented actions for changing (like toggling the boolean value with left/right), but if something more complex is needed, like a list of predefined values, it will need to be implemented in other menu files. 6. Open `menu/menu_displaylist.c` 7. Find your variables section and add `{MENU_ENUM_LABEL_NOTIFICATION_SHOW_AUTOCONFIG_FAILS, PARSE_ONLY_BOOL, false },` the position of this command in the list is what determines the order of the menu entries, the first run is at the top of the list. 8. Open `ui/drivers/qt/qt_options.cpp` 9. Find the corresponding menu and add the option, in this case `notificationsGroup->add(MENU_ENUM_LABEL_NOTIFICATION_SHOW_AUTOCONFIG);`. This represents the menu item in the desktop menu. # Finishing This guide only introduces the English menu labels. Translations are handled via Crowdin, after the pull request is accepted, new strings will appear for translators. New items wil be shown to users in English until translation is done. There are several possibilities that can be done with the menu system, but most require additional functions. Help text may also be defined (a slightly longer description that can be displayed with Select button). Some of the menu code is dynamic depending on e.g. number of users, those items usually require extra care. Icon assignments are handled in the menu drivers (ozone, xmb, glui). ================================================ FILE: docs/development/retroarch/new-translations-crowdin.md ================================================ # Helping With RetroArch Translations As libretro, it is very important for us that RetroArch can be easily understood by everyone. Making multiple languages available in RetroArch will ensure a better understanding of the options and a better experience for more people. Currently, RetroArch is in the process of being translated into over 35 languages. In the pursuit of streamlining the process and making it more accessible for new contributors we decided to utilise the crowdsourced translation service **Crowdin**[^1]. [^1]: https://crowdin.com/ - RetroArch and libretro are not affiliated in any way with Crowdin. ## What is Crowdin? Crowdin is a closed-source cloud-based localization technology and services company. Its main attraction is an Online Translation Editor, with which texts can be translated and proofread. Crowdin’s free to use for translators and open-source projects, like RetroArch. You can reach the project page of RetroArch by clicking [here](https://crowdin.com/project/retroarch). ### How to register a new account in Crowdin You need to create a Crowdin account in order to access the translation features of the site. You can do so by clicking [this link](https://accounts.crowdin.com/register) or by clicking the ‘**Sign up**’ button at the top right of the Crowdin site. Once you have created your Crowdin account, you can start translating.
![Position of the "Sign up" button](../../image/development/crowdin-sign-up.png){align=center}
Figure 1: Click 'Sign up' to register a new account in Crowdin's service.
### Enabling e-mail notifications/Joining a project You can add translations and suggestions to the project regardless of whether you join it or not. But if you join the project, Crowdin will notify you via e-mail about any changes and developments regarding the translation efforts (like recently added texts, etc.). You will also have a link to the RetroArch project added to your profile page for quick access. If you want to join the project, just click the ‘**Join**’ button at the top right of the project page.
![Join the Project](../../image/development/crowdin-join.png)
Figure 2: Click 'Join' to follow the project and receive e-mail notifications.
## Basic Instructions ### How to translate strings After selecting the language you want to translate to (you may request additional languages at the `#retroarch-translations` channel of our Discord[^2]), you will be welcomed by the file selection page. At the moment the most important files are _msg\_hash\_us.json_, which contains the (options) texts of the RetroArch program, as well as _googleplay\_us.json_ and _steam\_us.json_, which contain RetroArch’s Google Store and Steam page descriptions, respectively. [^2]: The official RetroArch Discord server: https://ra-link.web.app/discord
![File selection page](../../image/development/crowdin-file-selection.png)
Figure 3: The file selection page will show the amount of work that has been done in the chosen language.
Pick the file that you want to work on and you will be taken to the translation page. This screen can seem overwhelming at first, but don't worry: it's actually a very simple process.
![The main translation page](../../image/development/crowdin-translation-page.png)
Figure 4: The main translation page. On the left: search & source string selection; middle: translation area; on the right: empty comments section.
On the column located at the left side of your browser you will see a list of strings (a string is a piece of text). They will be marked by either a green check mark, marking strings with approved translations (see 'The final say – Proofreaders' below), a green dot for translated strings, for which you may add an alternative translation and/or vote on existing ones, or a red dot for as of yet untranslated strings. Click on any string to see them in the middle area. The **Source String** (the original English text) will be displayed at the top with a unique label, which can be used to search for this particular string, and possibly some context cues, like screenshots, right below it. There you will also find the ‘**Request**’ link, which is a shortcut for writing a comment asking for more information about the context. Below that is an area for writing the string’s translation. Once you have finished writing the translation for this string, click on the ‘**Save**’ button and your translation will be added to the list of suggested translations for this string right below. That’s it, simple as that. In the very few cases where the source string can be kept as-is, you can click the ‘**Copy Source**’ button ![Copy Source](../../image/development/crowdin-copy-source.png) to do so. In the string list (on the left side of the screen) some strings have a balloon icon ![Comments icon](../../image/development/crowdin-comments-icon.png). This icon shows that the string has comments written by other translators and developers. Comments may include interesting and/or important information that could help you decide on how best to translate a specific string. You can also write comments in case you have questions or additional information regarding any particular string. Please make sure that any comment you write is in __English__, as that is the official project language and the comments are visible to _everyone_. Comments will be displayed at Crowdin’s right column. In case there are no comments being displayed there, make sure that the left-most button of that column is active.
![Comments tab](../../image/development/crowdin-comments-tab.png)
Figure 5: The right-side column will display any available comments if its left tab is active.
### Machine Translation, Translation Memory and Other Languages Below the suggested translations in your language you will see two sections: “**TM and MT suggestions**” and “**Other Languages**”.
![Suggested translations](../../image/development/crowdin-suggested-translations.png)
Figure 6: The suggested translations area, located at the bottom half part of the page. This is the proofreaders view; no voting buttons, only approve & delete. Below that is the TM & MT section.
In the first, translation suggestions from the **Translation Memory** are displayed: those are derived from **the history of any existing translations**, both current and old, that appear to be a good match to the current string. These translations were once suggested by translators and can serve either as a convenient way to copy an existing translation or as a base/inspiration for your own. In addition to that there’s **Machine Translations**, provided by Crowdin Translate or Microsoft Translate. These are similar to what you’d expect from Google Translate: translations generated by an algorithm, without taking any context into account. **We strongly suggest that you use Machine Translations with caution, as they tend to fail at translating more exotic words & phrases and to be grammatically faulty.** Apart from that, they can be a useful source of inspiration for your own translations. Lastly, in the **Other Languages** section you will find translations from, well, other languages. If you know additional languages or your language’s way of writing is close to another one, you can use these translations as a reference and additional source of context.
![Other languages](../../image/development/crowdin-other-languages.png)
Figure 7: The Other Languages section is located right below the "TM and MT translations" area. The green check marks on the left side point out approved translations.
### Deciding the best translation – Voting Since multiple translations can be suggested for each source string and language, but obviously only one can ultimately be displayed to the users, we need to somehow decide which one to pick. Thankfully, Crowdin does most of the work for us: first, all translations are ordered by their age, newest to oldest; and second, and more importantly, Crowdin utilises a voting system to allow translators to up-vote translations they like and down-vote lacklustre/flawed ones. Voting is very simple: At the bottom half of the middle section of the translation page you’ll find a list of suggested translations. To the right of each suggestion are a couple buttons which can be used to add a positive or negative vote, either elevating the translations priority or decreasing it, respectively. Those votes can be un-/redone at any time, so no worries if you should change your mind later. ### The final say – Proofreaders But even with a voting system in place, at some point we would probably want to just decide on an official translation, which will be chosen regardless of the votes. That’s where proofreaders come into play. First things first: **in order to become a proofreader, translators will need additional authorization by RetroArch’s translation managers.** We suggest you contact us at the `#retroarch-translations` channel, located in RetroArch’s Discord server[^2], in order to discuss this authorization. As a proofreader, you don’t get to vote on the translations any more. Instead, if you find a translation to be suitable and free of errors you can click on the ![Approve button](../../image/development/crowdin-approve-button.png) button to _approve_ it. Approving a translation makes it the ‘default’ and elevates it above all others. Only one translation can be approved at a time for each source string and language. Translators can still vote on it, though, and it would be wise to rethink one's choice if the votes demand it. In addition to approving translations, proofreaders also may delete _any_ suggested translation, not just their own. It should be easy to see why additional authorization is needed for this position. ### Seeing results in the app For languages already included in RetroArch the translations are updated daily for the main app and weekly every Friday for cores. Other languages will need to be incorporated into the code of RetroArch and the cores. Once at least 15% of the `msg_hash_us.h` file is translated, the Crowdin managers will start work on including this language in the app. If you'd like to take matters in your own hands, you can find instructions [here](new-translations.md). ## Advanced Instructions ### What are things like \n or %d? Since RetroArch and libretro are C/C++ projects, the strings will sometimes contain 'special (sequences of) characters' used in code. Some people like to call them control codes, variables, etc., but the exact name is not important for translation purposes. Here are some of the most common examples:
![line break character](../../image/development/crowdin-line-break.png)
Figure 8: Example for the line break character \n; this is text for the 3DS menu, which has very short lines.
- **\n** is a line break/new line character: **it marks the end of the previous & the beginning of a new line.** Basically, it's like hitting the Enter button, but for programmers. Only used either for formatting/readability (use/remove them at your own discretion), or when line length is limited (use more or fewer than in the source string, as required; please pay attention to comments on that matter!). - A percentage sign (%) followed directly by one (rarely more) lowercase letter(s) (for example: %d, %ld, %u, %lu, %f, %lf, %s...), or sometimes even a number, is usually a placeholder. They will be replaced in the code with something else: numbers, other texts (usually names/objects not requiring translation)... You may move them around the text, but you must use all of them, and in the same order, or it could result in an error in RetroArch and nobody wants that.
![placeholders](../../image/development/crowdin-placeholders.png)
Figure 9: Example for placeholders; in this case two text placeholders are used (%s -> string).
This is not a complete list — there are quite a few more. But don't worry: in Crowdin these special elements are marked accordingly, and you will receive reminders should you forget to use them in your translations. And always remember: if there is something unclear about a source text, just ask about it in a comment on Crowdin or on Discord[^2]!
![special placeholder](../../image/development/crowdin-placeholder-special.png)
Figure 10: A special placeholder for text. Don't worry about it's exact purpose, just remember that there exist many exceptions not explicitly listed in this section.
### How to check the translations of other strings The best way to check for other translations, without having to leave the current string you are editing, is by using the middle button of the bar to the right of your screen. Here you can type any word to search through your language's Translation Memory (TM). The TM not only contains automatic translations of the strings, but also previously accepted/approved translations. Make sure you check the date of the text you want to use as a reference.
![Translation Memory](../../image/development/crowdin-tm.png)
Figure 11: You can find the Translation Memory on the middle tab of the right panel.
![Translation Memory](../../image/development/crowdin-tm-search.png)
Figure 12: The TM will show you source texts containing your search term and their current translation.
### How to find previous translations of words/phrases In the ‘Source String’ area you’ll find some words that are underlined. These are words that contain references to existing translations. Hover your mouse over these words to see the current translation references. As of the writing of this document, there are two types of references: - **Glossary terms**: These terms have been selected/translated by other members of the translation team (or other language teams, depending on the case) and should be used as much as possible. If you'd like to change an existing glossary term translation, please talk about it with any active translators of your language first. If your language currently does not have translators, but its progress is very high, do not change the existing terms on your own. Please contact other people on e.g. Discord[^2] and try to reach a consensus. - **Previous translations**: Crowdin will routinely check for repeated words and show what it thinks is a good translation based on previous input. These suggestions are marked with "Previously translated as:". This system is not perfect and should not be entirely trusted.
![Glossary translation](../../image/development/crowdin-gl-translation.png)
Figure 13: A term with a glossary translation.
![Previously translated as](../../image/development/crowdin-previously-translated-as.png)
Figure 14: A term with automatic translation suggestions based on previous input.
### Adding translations to the glossary **If your language has one or more active translators, please refrain from changing translated glossary terms of your language unless you have previously discussed it.** It's not fair to come around changing things without a proper debate. If you want to add a localized equivalent to an existing English term, you can do the following: 1. Click on the right icon on the bar to the right of your screen. 2. If the term is not being used by the Source String you are at this moment, use the Search function of this bar. 3. Click on the Edit button under the term. 4. The **Edit Term** window will appear. Below the name of your language, add your desired translation at the **Term** area. 5. You can also add a localized description under the Term area. Use it to add details/more information about the term and what it is referring to, etc. Context is key. 6. Then click on the Save button.
![Glossary terms](../../image/development/crowdin-gl-terms.png)
Figure 15: You can find the Glossary Terms on the the right tab of the right panel.
![Edit term](../../image/development/crowdin-gl-edit-term.png)
Figure 16: The Edit Term window.
**A word of warning**: do not change the source language's "**Part of speech**" section. Some terms have the option "Not selected" picked on purpose because Crowdin, sometimes, will not mark words as containing a Glossary term. For those in the know, Crowdin seems to have a syntax analysis function enabled for English, but it's far from perfect in its current state. ### Only for veteran users: Creating new terms in the glossary First and foremost, in its current state, the English words in the glossary should cover the entire RetroArch translation. Unless you _ABSOLUTELY_ need it, please refrain from creating new terms. **IMPORTANT**: search for the term you'd like to create first to avoid duplicates. If you have to add a new term to the Glossary, and it's absolutely necessary, follow these instructions: 1. Open the **Glossary Terms** as before and click on the icon that's to the left of the search bar, the one that has a plus (+) icon. 2. The **Add Term** window will appear. Go to the Term text box in the English section and write the English words that you want to classify with a term. 1. Alternatively, mark a term in a source string by selecting it with the mouse; a context menu should pop up. Click on “**Create Term**” & the Add Term window will open, with the selected term already filled in. 3. Add a description in English if possible. This will help translators of other languages understand the exact meaning of the term. Context is key. 4. Now go to the section that is below your language's name. Add your translation at the Term area. 5. You can also add a localized description under this Term area. Use it to add details/more information about the term and what it is referring to, etc. Once again, _context is key_.
![Add glossary terms](../../image/development/crowdin-gl-terms-add.png)
Figure 17: To create a new term, click on the button highlighted in yellow.
![Add term](../../image/development/crowdin-gl-add-term.png)
Figure 18: The Add Term window differs little from the Edit Term window.
================================================ FILE: docs/development/retroarch/new-translations.md ================================================ # Adding New Languages to RetroArch While translation is handled via the Crowdin[^1] platform ([more here](new-translations-crowdin.md)), RetroArch's code must be adjusted to display new languages. ## Files to change * `msg_hash.c` * `msg_hash.h` * `retroarch.c` * `translation_defines.h` * `intl/msg_hash_us.h` * `menu/menu_setting.c` * `tasks/task_translation.c` * `libretro-common/include/libretro.h` > Every new language must first be added to the project on Crowdin. This will ensure that a corresponding `intl/msg_hash_xx.h` file is created. Requests are accepted at the `#retroarch-translations` channel of the RetroArch Discord[^2]. [^1]: https://crowdin.com/ - RetroArch and libretro are not affiliated in any way with Crowdin. [^2]: The official RetroArch Discord server: https://ra-link.web.app/discord ## Main Instructions To add a language with the English name `XXXXX` and two-letter code `xx` (be sure to use the same one as in the corresponding `intl/msg_hash_xx.h` file) follow these steps: 1. Open `libretro-common/include/libretro.h`. 1. Add a `RETRO_LANGUAGE_XXXXX` item to the `retro_language` enum just above `RETRO_LANGUAGE_LAST`, using the next available integer value. > Do not rearrange the elements of this list! This would break the language association for the cores! 2. Open `msg_hash.h`. 1. Check if a `MENU_ENUM_LABEL_VALUE_LANG_XXXXX` item for your language is present in the `msg_hash_enums` enum; if not, add it. 3. Open `msg_hash.c`. 1. Add the following block inside the `get_user_language_iso639_1(bool limit)` function: ```c case RETRO_LANGUAGE_XXXXX: return "xx"; ``` 2. Add the following block inside the `msg_hash_to_str(enum msg_hash_enums msg)` function: ```c case RETRO_LANGUAGE_XXXXX: ret = msg_hash_to_str_xx(msg); break; ``` 3. Add a new static function: ```c static const char *msg_hash_to_str_xx(enum msg_hash_enums msg) { switch (msg) { #include "intl/msg_hash_xx.h" default: break; } return "null"; } ``` 4. Decide if `intl/msg_hash_xx.h` should use UTF-8 + BOM encoding. See the section below. 5. Open `intl/msg_hash_us.h`. 1. Check if the following block is present, where `Yyyyy` is the native name of the language and if not, add it: ```c MSG_HASH( MENU_ENUM_LABEL_VALUE_LANG_XXXXX, "Xxxxx - Yyyyy" ) ``` 6. Open `menu/menu_setting.c`. 1. Add the following assignment to the `setting_get_string_representation_uint_user_language()` function, before `if (*msg_hash_get_uint(MSG_HASH_USER_LANGUAGE) == RETRO_LANGUAGE_ENGLISH)` statement: ```c LANG_DATA(XXXXX) ``` 2. Add the following block inside the `setting_get_string_representation_uint_ai_service_lang()` function: ```c case TRANSLATION_LANG_XX: enum_idx = MENU_ENUM_LABEL_VALUE_LANG_XXXXX; break; ``` 7. Open `retroarch.c`. 1. Add your language to `enum retro_language retroarch_get_language_from_iso(const char *iso639)`: ```c {"xx", RETRO_LANGUAGE_XXXXX}, ``` 8. Open `tasks/task_translation.c`. 1. Add the following block inside the `ai_service_get_str(enum translation_lang id)` function: ```c case TRANSLATION_LANG_XX: return "xx"; ``` 9. Open `translation_defines.h`. 1. Add your language to the `translation_lang` enum between `TRANSLATION_LANG_DONT_CARE` and `TRANSLATION_LANG_LAST`items: ```c TRANSLATION_LANG_XX, /* Xxxxx */ ``` ## Optional Adjustments ### Generating custom font for RGUI The tutorial down below is taken from [trngaje's page.](https://trngaje.github.io/retroarch/retroarch-rgui-font/) First of all, I will explain the basic font, English font. It was 5x10 in size at first. If you analyze the first letter of !… hexadecimal value `0x80, 0x10, 0x42, 0x08, 0x20, 0x00, 0x00,` Convert to Binary ``` 1000 0000 0001 0000 0100 0010 0000 1000 0010 0000 0000 0000 ``` Place it in a little endian and cut it into 5 pixels ``` 00000 00100 00100 00100 00100 00100 00000 00100 00000000 ``` The source code in retroarch for this is as follows. ``` unsigned font_pixel = x + y * FONT_WIDTH; uint8_t rem = 1 << (font_pixel & 7); unsigned offset = font_pixel >> 3; uint8_t col = (bitmap_bin[FONT_OFFSET(letter) + offset] & rem) ? 0xff : 0; ``` The font was recreated by IlDucci’s request to improve the second Cyrillic language display error. It was 6x10 in size at first. ![image](https://user-images.githubusercontent.com/4651944/192516266-58bebc83-9e58-4fb1-aae9-8614f26e68bc.png) Each letter is separated by 16 pixels, of which only 6x10 is a meaningful area. For this purpose, I created a conversion program using the SDL function. It can be generated simply as follows. ``` ./png2c bitmap_cyrillic.png ``` Please refer to the location below for the code to build. https://github.com/trngaje/png2c You can download prebuilt images for Windows from the path below. https://github.com/trngaje/png2c/releases/tag/windows_64bit_png2c_220924 unzip windows_64bit_png2c_prebuild_220924.zip ``` png2c.exe bitmap_cyrillic.png ``` ### RGUI Compatibility To make the new language usable with the RGUI menu driver: 1. Open `menu/drivers/rgui.c`. 2. Navigate to the `rgui_fonts_init(rgui_t *rgui)` function. 3. Add `case RETRO_LANGUAGE_XXXXX:` to 1. the extended ASCII section if the new language uses the Basic Latin/ASCII + Latin-1 Supplement range of UTF-8 or 2. any other present language the new language shares the alphabet with (like Russian). 4. If a new language was added, it is important to compile RetroArch with the changes and ensure the new language works correctly with RGUI. 5. If your language uses a different range of symbols, an RGUI compatible font must be added first. This is an extensive process, which is outside the scope of this article. ### Narrator support 1. For Mac. (compatible with **say**) 1. Open `frontend/drivers/platform_darwin.m`. 2. Go to `accessibility_mac_language_code(const char* language)` function. Check if the following block is present, where `Yyyyy` is the voice name for the language and if not, add it before `return ""`: ```c else if (string_is_equal(language,"xx")) return "Yyyyy"; ``` 2. For Linux. (compatible with **[espeak](https://github.com/espeak-ng/espeak-ng)**) 1. Open `frontend/drivers/platform_unix.c`. 2. Go to `accessibility_unix_language_code(const char* language)` function. Check if the following block is present, where `yyy` is the [Identifier](https://github.com/espeak-ng/espeak-ng/blob/master/docs/languages.md) for the language and if not, add it before `/* default voice as fallback */`: ```c else if (string_is_equal(language, "xx")) return "yyy"; ``` 3. For Windows. (OS compatiable) 1. Open `frontend/drivers/platform_win32.c`. 2. Go to `accessibility_win_language_code(const char* language)` function. Check if the following block is present, where `Yyyyy` is the [voice name](https://support.microsoft.com/en-us/windows/appendix-a-supported-languages-and-voices-4486e345-7730-53da-fcfe-55cc64300f01#WindowsVersion=Windows_10) for the language and if not, add it before `return ""`: ```c else if (string_is_equal(language,"xx")) return "Microsoft Yyyyy Desktop"; ``` ## Encoding of translation files Translation files (`intl/msg_hash_xx.h`) in general must be UTF-8 encoded. For some languages, these files need to have a "UTF-8 Unicode (with [BOM](https://en.wikipedia.org/wiki/Byte_order_mark))" encoding. This can be done using the 'Encoding' option of editors like Notepad++ and Notepadqq. AFAIK, this is because of a requirement of the MSVC compilers for the Windows platform. Examples of this as of now are: * `msg_hash_ar.c` * `msg_hash_chs.h` * `msg_hash_cht.h` * `msg_hash_ja.h` * `msg_hash_ko.h` * `msg_hash_pl.h` * `msg_hash_ru.h` * `msg_hash_vn.h` Be careful when creating and editing your new translation files, as some text editors do strip the BOM without warning. ## Examples ### Adding languages to RetroArch * Arabic: * [add basic support for arabic.](https://github.com/libretro/RetroArch/commit/45580cb9a8f0fcd0a87f00eadf26d87f05289485) * [add byte-order-marker to msg_hash_ar.*](https://github.com/libretro/RetroArch/commit/d8f1a08a4758851d5530d311303146257cbf8216) * [Add "Arabic" to intl/msg_hash_us.h missed in 45580cb.](https://github.com/libretro/RetroArch/commit/7a0428fc769fd0eca663207134bec311aa3e30f3) * Indonesian, Swedish and Ukrainian (+RGUI): * [Add Indonesian, Swedish and Ukrainian language options](https://github.com/libretro/RetroArch/commit/311fec15d9db10ab14c879e898a8205dd37f827c) * [List of merges related to adding languages](https://github.com/libretro/RetroArch/pulls?q=is%3Apr+is%3Amerged+in%3Atitle+add+language+option+) ## Translation If you speak the target language `xx` then you could start translating on Crowdin. Instructions and recommended reading for that can be found [here](https://docs.libretro.com/development/retroarch/new-translations-crowdin/). > Please **do not change** the `intl/msg_hash_xx.h` files directly! Starting from early 2023, the help texts that were located in `intl/msg_hash_xx.c` files are also included on Crowdin. If you have translation efforts in `msg_hash_xx.c` file from an earlier date, you can copy them to Crowdin, with following caveats: * Individual line breaks (\n) at the end of each line are not required, current menu drivers will break lines automatically. Line break may be used as a paragraph separator, if text is long. * Make sure translations still matches the current source text, as several of those were updated during the refactor. * Do not exceed maximum line length (500 characters). * The Crowdin translations for these strings will only take effect when the definition is removed from `intl/msg_hash_xx.c`. ## See also * [Adding a RetroArch menu option](new-menu-options.md) * [Helping with RetroArch translations](new-translations-crowdin.md) ================================================ FILE: docs/development/shader/cg-shaders.md ================================================ # Developing Legacy Cg Shaders !!! Warning "Cg Shaders are deprecated" Cg has been discontinued for years and is closed source. Developers cannot use Cg for newer APIs such as Vulkan, D3D12, and Metal. Cg cross-compilation to GLSL is unmaintainable. We cannot do the Cg transform in runtime on mobile due to lack of open source Cg runtime. ## New Slang Shader Specification Unless you are developing shaders for a platform that cannot support the newer Slang standard, please consider [developing a Slang shader](slang-shaders.md) instead. ## Example Cg/HLSL program If you were to process an image on a CPU, you would most likely do something like this: ```c for(unsigned y = 0; y < height ; y++) { for(unsigned x = 0; x < width ; x++) out_pixel[y][x] = process_pixel(in_pixel[y][x], y,x); } ``` We quickly realize that this is highly serial and slow. We see that `out_pixel[y][x]` isn’t dependent on `out_pixel[y + k][x + k]`, so we see that we can parallelize quite a bit. Essentially, we only need to implement `process_pixel()` as a single function, which is called thousands, even millions of time every frame. The only purpose in life for `process_pixel()` is to process an input, and produce an output. No state is needed, thus, a “pure” function in computer science terms. For the Cg program, we need to implement two different functions. `main_vertex()` takes care of transforming every incoming vertex from camera space down to clip space. This essentially means projection of 3D (coordinates on GPU) down to 2D (your screen). Since we’re dealing with old school emulators here, which are already 2D, the vertex shading is very trivial. Vertex shaders get various coordinates as input, and uniforms. Every vertex emitted by the emulator is run through `main_vertex` which calculates the final output position. For our emulators this is just 4 times, since we’re rendering a quad on the screen. 3D games would obviously have a lot more vertices. While coordinates differ for each invocation, uniforms are constant through-out every call. Think of it as a global variable that you’re not allowed to change. Vertex shading can almost be ignored altogether, but since the vertex shader is run only 4 times, and the fragment shader is run millions of times per frame, it is a good idea to precalculate values in vertex shader that can later be used in fragment shader. There are some limitations to this which will be mentioned later. `main_fragment()` takes care of calculating a pixel color for every single out-put pixel on the screen. If you’re playing at 1080p, the fragment shader will have to be run `1920 * 1080` times! This is obviously straining on the GPU unless the shader is written efficiently. Obviously, main_fragment is where the real action happens. For many shaders we can stick with a “dummy” vertex shader which does some very simple stuff. The fragment shader receives a handle to a texture (the game frame itself), and the texture coordinate for the current pixel, and a bunch of uniforms. A fragment shader’s final output is a color, simple as that. Processing ends here. ## Shader Hello World We’ll start off with the basic vertex shader. No fancy things are being done. You’ll see a similar vertex shader in most of the Cg programs out there in the wild. ```c void main_vertex (float4 pos : POSITION, out float4 out_pos : POSITION, uniform float4x4 modelViewProj, float4 color : COLOR, out float4 out_color : COLOR, float2 tex : TEXCOORD, out float2 out_tex : TEXCOORD ) { out_pos = mul(modelViewProj, pos); out_color = color ; out_tex = tex ; } ``` This looks vaguely familiar to C, and it is. Cg stands for “C for graphics” after all. We notice some things are happening, notable some new types. ### Cg types #### Float `float4` is a vector type. It contains 4 elements. It could be colors, positions, whatever. It's used for vector processing which the GPUs are extremely efficient at. ### Semantics We see various semantics. The `POSITION` semantic means that the variable is tied to vertex coordinates. We see that we have an input `POSITION`, and an output (out) `POSITION`. We thus transform the input to the output with a matrix multiply with the current model-view projection. Since this matrix is the same for every vertex, it is a uniform. Remember that the variable names DO matter. modelViewProj has to be called exactly that, as the emulator will pass the MVP to this uniform. It is in the specification. Since we have semantics for the `POSITION`, etc, we can call them whatever we want, as the Cg environment figures out what the variables mean. The transformation happens here: ```c out_pos = mul(modelViewProj , pos); ``` The `COLOR` semantic isn’t very interesting for us, but the example code in nVidias Cg documentation includes it, so we just follow along. `TEXCOORD` is the texture coordinate we get from the emulator, and generally we just pass it to the fragment shader directly. The coordinate will then be linearly interpolated across the fragments. More complex shaders can output (almost) as many variables they want, that will be linearily interpolated for free to the fragment shader. We also need a fragment shader to go along with the vertex shader, and here's a basic shader that only outputs the pixel as-is. This is pretty much the result you’d get if you didn’t run any shader (fixed-function) at all. ```c float4 main_fragment ( uniform sampler2D s0 : TEXUNIT0, float2 tex : TEXCOORD) : COLOR { return tex2D ( s0 , tex ) ; } ``` This is arguably simpler than the vertex shader. Important to notice are: * `sampler2D` is a handle to a texture in Cg. The semantic here is `TEXUNIT0`, which means that it refers to the texture in texture unit 0. This is also part of the specification. * `float2 tex : TEXCOORD` is the interpolated coordinate we received from the vertex shader. * `tex2D(s0, tex);` simply does texture lookup and returns a `COLOR`, which is emitted to the framebuffer. Practically every fragment does more than one texture lookup. For example, classic pixel shaders look at the neighbor pixels as well to determine the output. But where is the neighbor pixel? We’ll revise the fragment shader and try to make a really blurry shader to demonstrate. We now need to pull up some uniforms. We need to know how to modify our tex coordinates so that it points to a neighbor pixel. ```c struct input { float2 video_size ; float2 texture_size ; float2 output_size ; float frame_count ; }; float4 main_fragment ( uniform sampler2D s0 : TEXUNIT0, uniform input IN , float2 tex : TEXCOORD) : COLOR { float4 result = float4 ( 0. 0 ) ; float dx = 1.0 / IN. texture_size. x ; float dy = 1.0 / IN. texture_size. y ; // Grab some of the neighboring pixels and blend together for a very mushy blur. result += tex2D (s0 , tex + float2 (−dx, −dy)); result += tex2D (s0 , tex + float2 (dx, −dy)); result += tex2D (s0 , tex + float2 (0.0, 0.0)); result += tex2D (s0 , tex + float2 (−dx, 0.0)); return result / 4. 0 ; } ``` Here we use `IN.texture_size` to determine the the size of the texture. Since GL maps the whole texture to the interval `[0.0, 1.0]`, `1.0 / IN.texture_size` means we get the offset for a single pixel, simple enough. Almost every shader uses this. We can calculate these offsets in vertex shader to improve performance since the coordinates are linearily interpolated anyways, but that is for another time. ## Putting it together The final runnable product is a single `.cg` file with the `main_vertex` and `main_fragment` functions added together. Not very complicated. For the icing on the cake, you should add a license header. ```c /* Stupid blur shader. * Author : Your friendly neighbor. * License : We don't have those things! */ struct input { float2 video_size; float2 texture_size; float2 output_size; float frame_count; }; void main_vertex ( float4 pos : POSITION, out float4 out_pos : POSITION, uniform float4x4 modelViewProj , float4 color : COLOR, out float4 out_color : COLOR, float2 tex : TEXCOORD, out float2 out_tex : TEXCOORD ) { out_pos = mul( modelViewProj , pos ); out_color = color ; out_tex = tex ; } float4 main_fragment ( uniform sampler2D s0 : TEXUNIT0, uniform input IN, float2 tex : TEXCOORD ) : COLOR { float4 result = float4 ( 0. 0 ) ; float dx = 1.0 / IN.texture_size.x; float dy = 1.0 / IN.texture_size.y; // Grab some of the neighboring pixels and blend // together f o r a very mushy blur. result += tex2D ( s0 , tex + float2 (−dx, −dy)); result += tex2D ( s0 , tex + float2 (dx, −dy )); result += tex2D ( s0 , tex + float2 (0.0, 0.0)); result += tex2D ( s0 , tex + float2 (−dx, 0.0)); return result / 4.0; } ``` ## Result As you can see, it’s not a practical shader, but it shows the blurring effect to the extreme. ![A blurry Super Metroid shader](../../image/development/shaders/example-blurry-shader.jpg) ----------------------------------------------------------- ## Shader file format * `#` begins a comment; the rest of the line is ignored. * Format is: `key = value`. There can be as many spaces as you like in between * Values can be wrapped inside `"` for multiword strings (`foo = "hai u"`) * `#include` includes a config file * Path is relative to where config file was loaded unless an absolute path is chosen * Key/value pairs from an `#include` are read-only and cannot be modified ----------------------------------------------------------- ## Cg shader spec This spec is for the Cg shading language developed by nVidia. It wraps around OpenGL to make shaders written in Cg quite portable. Shaders written in Cg can also be used with Direct3D and PlayStation3. Cg shaders are also compatible with basic HLSL if some considerations are taken into account. They can even be automatically compiled into GLSL shaders, which makes Cg shaders a true “write once, run everywhere” shader format. We encourage new shaders targeting Libretro frontends to be written in this format. RetroArch supports both single-pass Cg shaders as well as multi-pass shaders and uses a custom Cg preset format (`.cgp`). ### Another example Cg shader ```c void main_vertex ( float4 position : POSITION, out float4 oPosition : POSITION, uniform float4x4 modelViewProj, float2 tex : TEXCOORD, out float2 oTex : TEXCOORD ) { oPosition = mul(modelViewProj, position); oTex = tex; } float4 main_fragment (float2 tex : TEXCOORD, uniform sampler2D s0 : TEXUNIT0) : COLOR { return tex2D(s0, tex); } ``` ### Example Cg preset ```c shaders = 2 shader0 = 4xBR-v3.9.cg scale_type0 = source scale0 = 4.0 filter_linear0 = false shader1 = dummy.cg filter_linear1 = true ``` ### Entry points: - Vertex: `main_vertex` - Fragment: `main_fragment` ### Texture unit All shaders work on texture unit `0` (the default). 2D textures must be used. Power-of-two sized textures are recommended for optimal visual quality. The shaders must deal with the actual picture data not filling out the entire texture. Incoming texture coordinates and uniforms provide this information. The texture coordinate origin is defined to be top-left oriented. A texture coordinate of `(0, 0)` will always refer to the top-left pixel of the visible frame. This is opposite of what most graphical APIs expect. The implementation must always ensure that this ordering is held for any texture that the shader has access to. !!! Note Every texture bound for a shader must have black border mode set. Sampling a texel outside the given texture coordinates must always return a pixel with RGBA values `(0, 0, 0, 0)`. ### Uniforms Some parameters will need to be passed to all shaders, both vertex and fragment program. A generic entry point for fragment shader will look like: ```c float4 main_fragment (float2 tex : TEXCOORD0, uniform input IN, uniform sampler2D s_p : TEXUNIT0) : COLOR {} ``` The input is a struct: ```c struct input { float2 video_size; float2 texture_size; float2 output_size; float frame_count; float frame_direction; }; ``` - `TEXCOORD0`: Texture coordinates for the current input frame will be passed in `TEXCOORD0`. (`TEXCOORD` is a valid alias for `TEXCOORD0`). - `COLOR0`: Although legal, no data of interest is passed here. You cannot assume anything about data in this stream. - `IN.video_size`: The size of the actual video data in the texture, e.g for a SNES this will be generally `(256, 224)` for normal resolution frames. - `IN.texture_size`: This is the size of the texture itself. Optimally power-of-two sized. - `IN.output_size`: The size of the video output. This is the size of the viewport shown on screen. - `IN.frame_count`: A counter of the frame number. This increases with 1 every frame. This value is really an integer, but needs to be float for CGs lack of integer uniforms. - `IN.frame_direction`: A number telling which direction the frames are flowing. For regular playing, this value should be `1.0`. While the game is rewinding, this value should be `-1.0`. - `modelViewProj`: This uniform needs to be set in vertex shader. It is a uniform for the current MVP transform. ### Pre-filtering Most of these shaders are intended to be used with a non-filtered input. Nearest-neighbor filtering on the textures themselves are preferred. Some shaders, like scanline will most likely prefer bilinear texture filtering. ## Cg meta-shader format ### Rationale The `.cg` files themselves contain no metadata necessary to perform advanced filtering. They also cannot process an effect in multiple passes, which is necessary for some effects. The CgFX format does exist, but it would need current shaders to be rewritten to a HLSL-esque format. It also suffers a problem mentioned below. Rather than putting everything into one file (XML shader format), this format is config file based. This greatly helps testing shader combinations as there is no need to rearrange code in one big file. Another plus with this approach is that a large library of .cg files can be used to combine many shaders without needing to redundantly copy code over. It also helps testing as it is possible to unit-test every pass separately completely seamless. ## Format The meta-shader format is based around the idea of a config file with the format: `key = value`. Values with spaces need to be wrapped in quotes: key = "value stuff". No .ini sections or similar are allowed. Meta-shaders may include comments, prefixed by the "#" character, both on their own in an otherwise empty line or at the end of a key = value pair. The meta-format has four purposes: - Combine several standalone .cg shaders into a multipass shader. - Define scaling parameters for each pass. I.e., a HQ2x shader might want to output with a scale of exactly 2x. - Control filtering of textures. Many shaders will want nearest-neighbor filtering, and some will want linear. - Define external lookup textures. Shaders can access external textures found in `.tga` files. ### Parameters #### `shaders` (int) This param defines how many .cg shaders will be loaded. This value must be at least one. The path to these shaders will be found as a string in parameters shader0, shader1, ... shaderN, and so on. The path is relative to the directory the meta-shader was loaded from. #### `filter_linearN` (boolean) This parameter defines how the texture of the result of pass `N` will be filtered. `N = 0` (pass 0) is the raw input frame, `N = 1` is result of the first pass, etc. (A boolean value here might be `true`/`false`/`1`/`0`). Should this value not be defined, the filtering option is implementation-defined. #### `float_framebufferN` (boolean) This parameters defines if shader `N` should render to a 32-bit floating point buffer. This only takes effect if shaderN is actually rendered to an FBO. This is useful for shaders which have to store FBO values outside `[0, 1]` range. #### `frame_count_modN` (int) This positive parameter defines which modulo to apply to `IN.frame_count`. `IN.frame_count` will take the value `frame_count % frame_count_modN`. #### `scale_typeN` (string) This can be set to one of these values: - `source`: Output size of shader pass `N` is relative to the input size as found in `IN.video_size`. Value is `float`. - `viewport`: Output size of shader pass `N` is relative to the size of the window viewport. Value is `float`. **This value can change over time if the user resizes their window!** - `absolute`: Output size is statically defined to a certain size. Useful for hi-res blenders or similar. If no scale type is assumed, it is assumed that it is set to `source` with `scaleN` set to `1.0`. It is possible to set `scale_type_xN` and `scale_type_yN` to specialize the scaling type in either direction. `scale_typeN` however overrides both of these. **Exceptions** - If no `scale_type` is set for the very last shader, it is assumed to output at the full resolution rather than assuming a scale of `1.0x`, and bypasses any frame-buffer object rendering. - If there is only one shader, it is also considered to be the very last shader. If any scale option is defined, it has to go through a frame-buffer object, and subsequently rendered to screen. The filtering option used when stretching is implementation defined. It is encouraged to not have any scaling parameters in last pass if you care about the filtering option here. - In first pass, should no scaling factor be defined, the implementation is free to choose a fitting scale. This means, that for a single pass shader, it is allowed for the implementation to set a scale, render to FBO, and stretch. (Rule above). #### `scaleN`, `scale_xN`, `scale_yN` (float/int) These values control the scaling params from `scale_typeN`. The values may be either floating or int depending on the type. `scaleN` controls both scaling type in horizontal and vertical directions. If `scaleN` is defined, `scale_xN` and `scale_yN` have no effect. `scale_xN` and `scale_yN` controls scaling properties for the directions separately. Should only one of these be defined, the other direction will assume a source scale with value `1.0`, i.e. no change in resolution. Should `scale_type_xN` and `scale_type_yN` be set to different values, the use of scaleN is undefined (i.e. if X-type is absolute (takes `int`), and Y-type is source (takes `float`).) #### `textures` (multiple strings) The textures param defines one or more lookup textures IDs. Several IDs are delimited with `;` such as `textures = "foo;bar"`. These IDs serves as the names for a Cg sampler uniform, such as `uniform sampler2D foo;` and `uniform sampler2D bar;` The path of the textures can be found in the IDs, i.e. `foo = image0.tga` and `bar = image1.tga`. The paths of these textures are relative to the directory the meta-shader was loaded from. It is also possible to control the filtering options of the lookup texture as a boolean option in `ID_linear = true/false`. For example `foo_linear = false` will force nearest neighbor filtering for texture `foo`. !!! Note If `ID_linear` is not set, it is assumed to be linearly filtered. The textures will be loaded "as-is", and coordinates `(0, 0)`, `(0, 1)`, `(1, 0)`, `(1, 1)` will correspond to the corners of the texture. Since the texture coordinates of the texture in TEXUNIT0 might not be as convenient, the texture coordinates for all lookup textures will be found in `TEXCOORD1`. !!! Warning You cannot assume which texture unit the lookup textures will be bound to! The implementation only guarantees to be able to load plain top-left non-RLE `.tga` files. It may provide possibilities to load `.png` and other popular formats. ## Multipass It is sometimes feasible to process an effect in several steps. ```c shaders = 2 shader0 = pass1.cg shader1 = pass2.cg scale_type0 = source scale0 = 2.0 filter_linear0 = true filter_linear1 = false ``` During multi-pass rendering, some additional uniforms are available. With multi-pass rendering, it is possible to utilize the resulting output for every pass that came before it, including the unfiltered input. This allows for an additive approach to shading rather than serial style. The unfiltered input can be found in the ORIG struct: - `uniform sampler2D ORIG.texture`: Texture handle. Must not be set to a predefined texture unit. - `uniform float2 ORIG.video_size`: The video size of original frame. - `uniform float2 ORIG.texture_size`: The texture size of original frame. - `in float2 ORIG.tex_coord`: An attribute input holding the texturecoordinates of original frame. - `PASS%u`: This struct holds the same data as the `ORIG` struct, although the result of passes {1, 2, 3 ...}, i.e. `PASS1.texture` holds the result of the first shader pass. If rendering pass `N`, passes `{1, ..., N-2}` are available. (`N-1` being input in the regular `IN` structure). - `PREV`: This struct holds the same data as the `ORIG` struct, and corresponds to the raw input image from the previous frame. Useful for motion blur. - `PREV1..6`: Similar struct as `PREV`, but holds the data for passes further back in time. `PREV1` is the frame before `PREV`, `PREV2` the frame before that again, and so on. This allows up to 8-tap motion blur. ================================================ FILE: docs/development/shader/content-aware-shaders.md ================================================ # Content-aware shaders Content-aware shaders grab data from the core state itself, such as emulator RAM data. This is only implemented for SNES so far, but the idea is quite extendable and portable. The basic idea is that we capture RAM data in a certain way (semantic if you will) from the SNES, and pass it as a uniform to the shader. The shader can thus act on game state in interesting ways. As a tool to show this feature, we’ll focus on replicating [the simple tech demo shown on YouTube](http://www.youtube.com/watch?v=4VzaE9q735k). What happens is that when Mario jumps in the water, the screen gets a "watery" effect applied to it, with a rain lookup texture, and a wavy effect. When he jumps out of the water, the water effect slowly fades away. We thus need to know two things: - Is Mario currently in water or not? - If not, how long time was it since he jumped out? Since shaders do not have state associated with it, we have to let the environment provide the state we need in a certain way. We’ll call this concept a semantic. To capture a RAM value directly, we can use the "capture" semantic. To record the time when the RAM value last changed, we can use the "transition" semantic. We obviously also need to know where in RAM we can find this information. Luckily, [the folks over at SMW Central know the answer](http://www.smwcentral.net/?p=map&type=ram). We see: ``` $7E :0075 , byte , Flag , Player is in water flag. #$00 = No; #$01 = Yes. ``` Bank `$7E` and `$7F` are mapped to WRAM `$0000-$FFFF` and `$10000-$1FFFF` respectively. Thus, our WRAM address is `$0075`. In the config file, we can now set up the uniforms we’ll want to be captured. ``` imports = "mario_water ; mario_water_time" mario_water_semantic = capture # Capture the RAM value as−is. mario_water_wram = 0075 # This value is hex! mario_water_time_semantic = transition # Capture the frame count when this variable last changed. # Use with IN. frame_count , to create a fade−out effect. mario_water_time_wram = 0075 ``` The amount of possible "semantics" are practically endless. It might be worthwhile to attempt some possibility to run custom code that keeps track of the shader uniforms in more sophisticated ways later on. Do note that there is also a `%s_mask` value which will let you bitmask the RAM value to check for bit-flags more easily. Now that we got that part down, let's work on the shader design. In the fragment shader we simply render both the full water effect, and the `«normal»` texture, and let a "blend" variable decide. We can say that `1.0` is full water effect, `0.0` is no effect. We can start working on our vertex shader. We will do something useful here for once. ```c struct input { float frame_count; }; void main_vertex ( float4 pos : POSITION, out float4 out_pos : POSITION, uniform float4x4 modelViewProj, float4 color : COLOR, out float4 out_color : COLOR, float2 tex : TEXCOORD0, out float2 out_tex : TEXCOORD0, float2 tex1 : TEXCOORD1, out float2 out_tex1 : TEXCOORD1, // Even if the data should have been int, Cg doesn't seem to support integer uniforms uniform float mario_water, uniform float mario_water_time, uniform input IN, // Blend factor is passed to fragment shader. We'll output the same value in every vertex, // so every fragment will get the same value for blend_factor since there is nothing to interpolate. out float blend_factor ) { out_pos = mul( modelViewProj , pos ); out_color = color; out_tex = tex; out_tex1 = tex1; float transition_time = 0.5 * (IN. frame_count mario_water_time ) / 60.0; // If Mario is in the water ( $0075 != 0), it's always 1... if ( mario_water > 0.0) blend_factor = 1.0; // Fade out from 1.0 towards 0.0 as transition_time grows larger. else blend_factor = exp(−transition_time ); } ``` All fine and dandy so far, now we just need to use this blend_factor in our fragment shader somehow... Let’s move on to the fragment shader where we blend. ```c float apply_wave ( float2 pos , float2 src , float cnt ) { float2 diff = pos − src ; float dist = 300.0 * sqrt(dot(diff , diff)); dist −= 0.15 ∗ cnt; return sin(dist); } // Fancy stuff to create a wave. float4 water_texture ( float4 output , float2 scale , float cnt ) { float res = apply_wave ( scale , src0 , cnt ) ; res += apply_wave ( scale , src1 , cnt ) ; res += apply_wave ( scale , src2 , cnt ) ; res += apply_wave ( scale , src3 , cnt ) ; res += apply_wave ( scale , src4 , cnt ) ; res += apply_wave ( scale , src5 , cnt ) ; res += apply_wave ( scale , src6 , cnt ) ; return output * (0.95 + 0.012 * res ) ; } float4 main_fragment ( uniform input IN , float2 tex : TEXCOORD0, uniform sampler2D s0 : TEXUNIT0, uniform sampler2D rain , float2 tex1 : TEXCOORD1, in float blend_factor // Passed from vertex ) : COLOR { float4 water_tex = water_texture ( tex2D (s0, tex), tex1, IN.frame_count ); float4 normal_tex = tex2D (s0 , tex); float4 rain_tex = tex2D (rain , tex1); // First , blend normal and water texture together , // then add the rain texture with alpha blending on top return lerp(lerp(normal_tex, water_tex, blend_factor), rain_tex, rain_tex.a * blend_factor * 0. 5); } ``` ### RetroArch config file ``` shaders = 1 shader0 = mario.cg filter_linear0 = true imports = "mario_water;mario_water_time" mario_water_semantic = capture mario_water_time_semantic = transition mario_water_wram = 0075 mario_water_time_wram = 0075 textures = rain rain = rain.tga rain_linear = true ``` ## How to test when developing for RetroArch To develop these kinds of shaders, I’d recommend using RetroArch w/Cg support, and a debugging tool for your emulator of choice to peek at RAM values (build it for bSNES yourself with `options=debugger`). After written, the shader should translate nicely over to RetroArch with some slight changes to the config. ## Results Here are some screenshots of the mario effect (in Super Mario World SNES) we developed. Obviously this is a very simple example showing what can be done. The imagination is the limit here. ### Prior to Mario jumping in water ![Super Mario World prior to Mario jumping in water.](../../image/development/shaders/content-aware-shader-1.jpg) ### After Mario jumps in water ![Super Mario World after Mario jumps in water](../../image/development/shaders/content-aware-shader-2.jpg) ================================================ FILE: docs/development/shader/glsl-shaders.md ================================================ # Developing GLSL Shaders Like Cg shaders, GLSL shaders represents a single pass, and requires a preset file to describe how multiple shaders are combined. The extension is `.glsl`. As GLSL shaders are normally placed in two different files (`vertex`, `fragment`), making it impractical to select in a menu. This is worked around by using compiler defines in order to be equivalent to Cg shaders. ## Example GLSL shader !!! Note GLSL shaders must be modern style, and using ruby prefix is discouraged. ```c varying vec2 tex_coord; #if defined(VERTEX) attribute vec2 TexCoord; attribute vec2 VertexCoord; uniform mat4 MVPMatrix; void main() { gl_Position = MVPMatrix * vec4(VertexCoord, 0.0, 1.0); tex_coord = TexCoord; } #elif defined(FRAGMENT) uniform sampler2D Texture; void main() { gl_FragColor = texture2D(Texture, tex_coord); } #endif ``` ### GLSL presets Like Cg shaders, there is a GLSL preset format. Instead of `.cgp` extension, `.glslp` extension is used. The format is exactly the same, just replace `.cg` shaders with `.glsl`. To convert a `.cgp` preset, rename to `.glslp` and replace all references to `.cg` shaders with `.glsl`. ## Converting from Cg shaders GLSL shaders are mostly considered a compatibility format. It is possible to compile Cg shaders into GLSL shaders automatically using our [cg2glsl script](https://github.com/libretro/RetroArch/blob/master/tools/cg2glsl.py). It can convert single shaders as well as batch conversion. Shader converstion relies on nVidia's `cgc` tool found in the `nvidia-cg-toolkit` package. ================================================ FILE: docs/development/shader/shader-lookup-textures.md ================================================ # Shader lookup textures A popular feature among RetroArch users the ability to access external textures. This means we have several samplers available for use. In the config file, we define the textures as so: ``` textures = " foo ; bar" foo = path_foo.png bar = bar_foo.png foo_linear = true # Linear filtering for foo. bar_linear = true # Linear filtering for bar. ``` RetroArch PS3 uses PNG as the main format, RetroArch can use whatever if Imlib2 support is compiled in. If not, it’s restricted to lop-left ordered, non-RLE TGA. From here on, `foo` and `bar` can be found as uniforms in the shaders. The texture coordinates for the lookup texture will be found in `TEXCOORD1`. This can simply be passed along with `TEXCOORD0` in the vertex shader as we did with `TEXCOORD0`. Here we make a fragment shader that blends in two background picture at a reduced opacity. Do NOT assign lookup textures to a certain `TEXUNIT`, Cg will assign a fitting texture unit to the sampler. ```c float4 main_fragment ( uniform sampler2D s0 : TEXUNIT0, uniform sampler2D foo, uniform sampler2D bar, float2 tex : TEXCOORD0, float2 tex_lut : TEXCOORD1) : COLOR { float4 bg_sum = (tex2D(foo, tex_lut) + tex2D (bar , tex_lut)) * 0.15; return lerp (tex2D(s0, tex), bg_sum, bg_sum.a); // Alpha blending. } ``` ## Results: a shader for drawing a background border ![Using a shader to draw a border](../../image/development/shaders/lookup-texture-shader.jpg) ================================================ FILE: docs/development/shader/shader-overview.md ================================================ # Shader Development Overview ## Available shader types As the reference libretro frontend, RetroArch supports three shader languages: | Shader Language | Video Context Drivers | | ----------------------------------- | --------------------- | | [Slang](slang-shaders.md) | Vulkan, GL 2.x (legacy desktop), GL 3.x+ (modern desktop), GLES2 (legacy mobile), GLES3 (modern mobile), HLSL (Planned), Metal (Planned) | | [GLSL](glsl-shaders.md) | GL Shading Language, OpenGL, OpenGL ES, and EGL contexts including KMS mode in Linux) | | [Cg (deprecated)](cg-shaders.md) | HLSL/GLSL, nVidia | | [XML (discontinued)](xml-shaders.md) | GLSL | When possible, it is recommended to use Slang shaders for supporting the widest variety of modern systems. RetroArch is able to stack these shaders to create a combined effect. These complex effects are saved with a special extension: - `.slangp` for Slang - `.glslp` for GLSL - `.cpg` for Cg ## Common Shaders Repository The Libretro organization hosts a [repository](https://github.com/libretro/common-shaders) on Github that contains a compilation of shaders. Users can contribute their own shaders to this repository by doing a Pull Request. ## Shader development: The rendering pipeline With shaders you are able to take control over a large chunk of the GPUs inner workings by writing your own programs that are uploaded and run on the GPU. In the old days, GPUs were a big black box that was highly configurable using endless amount of API calls. In more modern times, rather than giving you endless amounts of buttons, you are expected to implement the few `«buttons»` you actually need, and have a streamlined API. The rendering pipeline is somewhat complex, but we can in general simplify it to: - Vertex processing - Rasterization - Fragment processing - Framebuffer blend Shader developers can take control of what happens during vertex processing, and fragment processing. ## Frontend development: Rendering the shader chain With all these options, the rendering pipeline can become somewhat complex. The meta-shader format greatly utilizes the possibility of off-screen rendering to achieve its effects. In OpenGL usually this is referred to as frame-buffer objects, and in HLSL as render targets. This feature will be referred to as FBO from here. FBO texture is assumed to be a texture bound to the FBO. As long as the visual result is approximately identical, the implementation does not have to employ FBO. With multiple passes our chain looks like this conceptually: `|Source image| ---> |Shader 0| ---> |FBO 0| ---> |Shader 1| ---> |FBO 1| ---> |Shader 2| ---> (Back buffer)` In the case that Shader 2 has set some scaling params, we need to first render to an FBO before stretching it to the back buffer. `|Source image| ---> ... |Shader 2| ---> |FBO 2| ---> (Back buffer)` Scaling parameters determine the sizes of the FBOs. For visual fidelity it is recommended that power-of-two sized textures are bound to them. This is due to floating point inaccuracies that become far more apparent when not using power-of-two textures. If the absolute maximum size of the source image is known, then it is possible to preallocate the FBOs. Do note that the size of FBOn is determined by dimensions of `FBOn-1` when "source" scale is used, _not_ the source image size! Of course, FBO0 would use source image size, as there is no `FBO-1`. For example, with SNES there is a maximum width of `512` and height of `478`. If a source relative scale of `3.0x` is desired for first pass, it is thus safe to allocate a FBO with size of `2048x2048`. However, most frames will just use a tiny fraction of this texture. With "viewport" scale it might be necessary to reallocate the FBO in run-time if the user resizes the window. ## Shader compatibility with RetroArch video drivers In RetroArch, the following table specifies which shader types work with what video contexts: Context Driver | GLSL | CG | HLSL | Slang -----------------------|------------|---------|----------------|-------------- Android | Y | N | N | Y CGL | Y | N | N | N D3D | N | Y | N (Possible)| Y DRM | Y | N | N | N Emscripten | Y | N | N | N GDI | N | N | N | N KHR | N | N | N | Y Mali | Y | N | N | N Opendingux | Y | N | N | N OSMesa | Y | N | N | N PS3 | N | Y | N | N QNX | Y | N | N | N SDL | N | N | N | N VC | Y | N | N | N Vivante | Y | N | N | N Wayland | Y | N | N | Y WGL | Y | N | N | Y X | Y | Y | N | Y XEGL | Y | N | N | N !!! Warning Attempting to load unsupported shader types may result in segmentation faults because the context drivers currently do not have the behavior to declare which types of shaders it supports. ================================================ FILE: docs/development/shader/slang-shaders.md ================================================ # Developing Slang Shaders ## Target shader languages - Vulkan - GL 2.x (legacy desktop) - GL 3.x+ (modern desktop) - GLES2 (legacy mobile) - GLES3 (modern mobile) - HLSL - Metal **Design principle: Avoid mandating high-level features which do not work for GLES2.** RetroArch runs on GL, GL2, and GLES2. GL and GL2 are only relevant from a legacy standpoint, but GLES2 is stil a relevant target platform today and having GLES2 compatibility makes GL2 very easy. We therefore avoid a design which deliberately ruins GLES2 compatibility. However, we also do not want to artificially limit ourselves to shader features which are only available in GLES2. There are many shader builtins, for example, which only work in GLES3/GL3 and we should not hold back support in these cases. ## Why a new spec? The previous RetroArch shader subsystem in RetroArch is quite mature with a large body of shaders written for it. While it has served us well, it was not forward-compatible. The current state of writing high-level shading languages that work everywhere is challenging. Up until now, we have relied on nVidia Cg to serve as a basic foundation for shaders, but Cg has been discontinued for years and is closed source. Developers cannot use Cg for newer APIs such as Vulkan, D3D12, and Metal. Cg cross-compilation to GLSL is unmaintainable. We cannot do the Cg transform in runtime on mobile due to lack of open source Cg runtime. Another alternative was to write straight-up GLSL, but this too has serious drawbacks. All the different GL versions and GLSL variants are different enough that it becomes painful to write portable GLSL code that works without modification. Examples include: - varying/attribute vs in/out (legacy vs modern) - precision qualifiers (GLSL vs ESSL) - texture2D vs texture (legacy vs modern) - Lack of standard support for `#include` to reduce copy-pasta The fundamental issue is that GLSL shaders are dependent on the runtime GL version, which makes it difficult to test all shader variants. We did not want to litter every shader with heaps of `#ifdefs` everywhere to combat this problem. We also wanted to avoid having to write pseudo-GLSL with some text-based replacement behind the scenes. ## Vulkan GLSL as the portable solution Fortunately, there is now a forward looking and promising solution to our problems. Vulkan GLSL is a GLSL dialect designed for Vulkan and SPIR-V intermediate representation. We can use whatever GLSL version we want when writing shaders, as it is decoupled from the GL runtime. In runtime, we can have a vendor-neutral mature compiler, [https://github.com/KhronosGroup/glslang](glslang) which compiles our Vulkan GLSL to SPIR-V. Using [https://github.com/KhronosGroup/SPIRV-Cross](SPIRV-Cross), we can then do reflection on the SPIR-V binary to deduce our filter chain layout. We can also disassemble back to our desired GLSL dialect in the GL backend based on which GL version we're running, which effectively means we can completely sidestep all our current problems with a pure GLSL based shading system. Another upside is that we no longer have to deal with vendor-specific quirks in the GLSL frontend. A common problem when people write for nVidia is that they mistakenly use `float2`/`float3`/`float4` types from Cg/HLSL, which is supported as an extension in their GLSL frontend. ## Why not SPIR-V directly? This was considered, but there are several convenience problems with having a shading spec around pure SPIR-V. The first problem is metadata. In GLSL, we can quite easily extend with custom `#pragmas` or similar, but there is no trivial way to do this in SPIR-V outside writing custom tools to emit special metadata as debug information or similar with OpSource. We could also have this metadata outside in a separate file, but juggling more files means more churn, which we should try to avoid. The other problem is convenience. If RetroArch only accepts SPIR-V, we would need an explicit build step outside RetroArch first before we could test a shader. This gets very annoying during shader development, so it is clear that we need to support GLSL anyway, making SPIR-V support largely redundant. The main argument for supporting SPIR-V would be to allow new shading languages to be used. This is a reasonable thing to consider, which is why the goal is to not design ourselves into a corner where it's only Vulkan GLSL that can possibly work down the line. We are open to the idea that new shading languages that target SPIR-V will emerge. ## High level Overview The RetroArch shader format outlines a filter chain/graph, a series of shader passes which operate on previously generated data to produce a final result. The goal is for every individual pass to access information from *all* previous shader passes, even across frames, easily. - The filter chain specifies a number of shader passes to be executed one after the other. - Each pass renders a full-screen quad to a texture of a certain resolution and format. - The resolution can be dependent on external information. - All filter chains begin at an input texture, which is created by a libretro core or similar. - All filter chains terminate by rendering to the "backbuffer". The backbuffer is somewhat special since the resolution of it cannot be controlled by the shader. It can also not be fed back into the filter chain later because the frontend (here RetroArch) will render UI elements and such on top of the final pass output. Let's first look at what we mean by filter chains and how far we can expand this idea. ### Simplest filter chain The simplest filter chain we can specify is a single pass. ```text (Input) -> [ Shader Pass #0 ] -> (Backbuffer) ``` In this case there are no offscreen render targets necessary since our input is rendered directly to screen. ### Multiple passes A trivial extension is to keep our straight line view of the world where each pass looks at the previous output. ```text (Input) -> [ Shader Pass #0 ] -> (Framebuffer) -> [ Shader Pass #1 ] -> (Backbuffer) ``` Framebuffer here might have a different resolution than both Input and Backbuffer. A very common scenario for this is separable filters where we first scale horizontally, then vertically. ### Multiple passes and multiple inputs There is no reason why we should restrict ourselves to a straight-line view. ```text /------------------------------------------------\ / v (Input) -> [ Shader Pass #0 ] -> (Framebuffer #0) -> [ Shader Pass #1 ] -> (Backbuffer) ``` In this scenario, we have two inputs to shader pass #1, both the original, untouched input as well as the result of a pass in-between. All the inputs to a pass can have different resolutions. We have a way to query the resolution of individual textures to allow highly controlled sampling. We are now at a point where we can express an arbitrarily complex filter graph, but we can do better. For certain effects, time (or rather, results from earlier frames) can be an important factor. ### Multiple passes, multiple inputs, with history ```text /------------------------------------------------\ / v (Input) -> (+feedback input) [ Shader Pass #0 ] (output) -> (Framebuffer #0) -> [ Shader Pass #1 ] -> (Backbuffer) ^ / \------------------------------------/ ``` This diagram shows a filter chain where a shader pass can take multiple inputs: the original input texture, the output from a previous pass, and feedback from a previous frame. The feedback input allows the shader to use data from the last frame, enabling effects like motion blur, persistence, or ghosting. Each pass can combine these inputs to produce its output, which is then used by subsequent passes or rendered to the backbuffer. For practical guidance on using feedback and history in shaders, see [Advanced Techniques: Practical Guide to Feedback and History](#advanced-techniques-practical-guide-to-feedback-and-history). ### Texture Clamping and Wrap Modes When sampling textures in a shader, the behavior for coordinates outside the [0, 1] range is determined by the texture's wrap mode. By default, all input and intermediate textures in the filter chain use `clamp_to_border` mode, with the border color set to transparent black (`vec4(0.0)`). This means that any sampling outside the texture returns transparent black unless otherwise specified. The wrap mode for each stage's input texture can be controlled in the preset file using the `wrap_modeN` option (where `N` is the pass index) or `NAME_wrap_mode` for external textures where `NAME` is the alias. The following wrap modes are supported: - **clamp_to_edge**: Coordinates outside [0, 1] are clamped to the nearest edge texel. Sampling outside the texture returns the value of the closest edge pixel. - **clamp_to_border** (default): Coordinates outside [0, 1] return the border color, which is always transparent black (`vec4(0.0)`). - **repeat**: Texture coordinates wrap around, so sampling outside [0, 1] repeats the texture in a tiled fashion. - **mirrored_repeat**: Texture coordinates outside [0, 1] are mirrored and then repeated, creating a seamless mirrored tiling effect. You can set the wrap mode for each texture or pass in the preset file, for example: ```ini wrap_mode0 = clamp_to_edge wrap_mode1 = mirrored_repeat foo_wrap_mode = clamp_to_edge bar_wrap_mode = repeat ``` This allows fine-grained control over how out-of-bounds texture sampling behaves for each stage or lookup texture. For most shader passes, the default `clamp_to_border` is safe, but for effects like tiling or seamless wrapping, `repeat` or `mirrored_repeat` may be preferred. When compositing external textures, especially with alpha channels, `clamp_to_border` may have unexpected results near edges, and `clamp_to_edge` may be preferred. From a practical standpoint, `clamp_to_border` is generally the most robust choice for filtering, while `clamp_to_edge` is generally the most robust choice for compositing. ### Runtime Resizing of Textures and Framebuffers To enable maximum flexibility, frontends take a hands-off approach to resizing textures and framebuffers during runtime. This allows shaders and presets to adapt dynamically to changing conditions, such as window resizing, core resolution changes, or user adjustments. There are three high-level stages for size management in the filter chain: **Input Stage:** - The base texture is provided by the core and is represented by the `OriginalSize` uniform. - The input size can change from frame to frame, depending on the core's output. **Intermediate Stages:** - Each shader pass outputs to a framebuffer whose size is controlled by the preset. - The size can be specified as an absolute value, as a size relative to the output of the previous shader stage (or `OriginalSize` for the first stage), or as a size relative to the viewport (the area requested by the frontend, represented by `FinalViewportSize`). - The size of the input to a pass is represented by the `SourceSize` uniform, and the size of the output is represented by the `OutputSize` uniform. **Output Stage:** - The final output may be the last shader in the chain, provided the swapchain format matches the requested format in that shader pass (e.g., 8-bit when frontend HDR is off, 10-bit when HDR is on, *and* `scale_typeN` is not used for that shader). - In all cases, the final output size is represented by the `FinalViewportSize` uniform. This flexible sizing system allows for complex scaling, multi-pass effects, and seamless adaptation to runtime changes. Shaders should always use the provided size uniforms (`OriginalSize`, `SourceSize`, `OutputSize`, `FinalViewportSize`) to ensure correct sampling and output, especially when resolutions may change dynamically. In addition, shaders can rely on the `OriginalAspect` uniform to know the requested aspect ratio of the core for correct presentation. No texture in the filter chain is padded at any time. It is possible for resolutions in the filter chain to vary over time, which is common with certain emulated systems. In these scenarios, the textures and framebuffers are simply resized appropriately. Older frames still keep their old resolution in the brief moment that the resolution is changing. It is very important that shaders do not blindly sample with nearest filter with any scale factor. If naive nearest neighbor sampling is to be used, shaders must either make sure that the filter chain is configured with integer scaling factors so that ambiguous texel-edge sampling is avoided, or align texture sampling with the texture's pixel grid. If you need to align sampling with the texture's pixel grid (for example, to avoid artifacts with nearest-neighbor sampling and non-integer scaling), see [the sampling alignment code example](#correctly-sampling-textures) later in this document. ### Deduce shader inputs by reflection We want to have as much useful information in the shader source as possible. We want to avoid having to explicitly write out metadata in shaders wherever we can. The biggest hurdle to overcome is how we describe our pipeline layout. The pipeline layout contains information about how we access resources such as uniforms and textures. There are six main types of inputs in this shader system. - Texture samplers (sampler2D) - Look-up textures for static input data - Uniform data describing dimensions of textures - Uniform ancillary data for render target dimensions, backbuffer target dimensions, frame count, etc - Uniform user-defined parameters - Uniform MVP for vertex shader #### Deduction by name There are two main approaches to deduce what a sampler2D uniform wants to sample from. The first way is to explicitly state somewhere else what that particular sampler needs, e.g. ```glsl uniform sampler2D geeWhatAmI; // Metadata somewhere else SAMPLER geeWhatAmI = Input[-2]; // Input frame from 2 frames ago ``` The other approach is to have built-in identifiers which correspond to certain textures. ```glsl // Source here being defined as the texture from previous framebuffer pass or the input texture if this is the first pass in the chain. uniform sampler2D Source; ``` In SPIR-V, we can use `OpName` to describe these names, so we do not require the original Vulkan GLSL source to perform this reflection. We use this approach throughout the specification. An identifier is mapped to an internal meaning (semantic). The shader backend looks at these semantics and constructs a filter chain based on all shaders in the chain. Identifiers can also have user defined meaning, either as an alias to existing identifiers or mapping to user defined parameters. ### Combining vertex and fragment into a single shader file One strength of Cg is its ability to contain multiple shader stages in the same .cg file. This is very convenient since we always want to consider vertex and fragment together. This is especially needed when trying to mix and match shaders in a GUI window for example. We don't want to require users to load first a vertex shader, then fragment manually. GLSL however does not support this out of the box. This means we need to define a light-weight system for preprocessing one GLSL source file into multiple stages. #### Do we make vertex optional? In most cases, the vertex shader will remain the same. This leaves us with the option to provide a "default" vertex stage if the shader stage is not defined, but at this time, a valid entry-point must always be present for both stages. Vertex shaders are also useful for performing precomputations that can reduce the workload of the fragment shader. For more information, see [Advanced Techniques: Vertex Precomputation](#vertex-precomputation). ### #include support With complex filter chains there is a lot of opportunity to reuse code. We therefore want light support for the #include directive. ### Required Shader Stages Every `.slang` shader file must define both a vertex and a fragment stage. This is accomplished using the `#pragma stage` directive. The convention is to place the vertex stage first, followed by the fragment stage. #### Universal Declarations Any code (such as uniform declarations, function definitions, or constants) written before the first `#pragma stage` directive is considered universal. These declarations are included in both the vertex and fragment shader stages. #### Scoped Declarations Once a `#pragma stage` directive is encountered, all subsequent code is scoped to that shader stage until the next `#pragma stage` is found. This allows you to write stage-specific code for either the vertex or fragment shader. #### Example Structure ```glsl #version 450 // Universal declarations uniform mat4 MVP; vec2 computeUV(vec2 pos) { ... } #pragma stage vertex // Vertex stage-specific code layout(location = 0) in vec2 position; void main() { gl_Position = MVP * vec4(position, 0.0, 1.0); } #pragma stage fragment // Fragment stage-specific code layout(location = 0) out vec4 FragColor; void main() { FragColor = vec4(1.0); } ``` #### Supported `#pragma stage` Types - `#pragma stage vertex`: Marks the beginning of the vertex shader stage code. - `#pragma stage fragment`: Marks the beginning of the fragment shader stage code. Both stages must be present for the shader to compile successfully. The order should be vertex first, then fragment. Any declarations before the first stage pragma are shared by both stages; declarations after a stage pragma are only visible to that stage until the next stage pragma. This structure ensures clarity and separation between universal and stage-specific code, making shader development more maintainable and less error-prone. ### `#pragma` directives: Required and Optional Most `#pragma` directives in a `.slang` file are optional and provide additional metadata or configuration for the shader system. However, there are two exceptions: `#pragma stage vertex` and `#pragma stage fragment` are required in every `.slang` file. These pragmas explicitly define the boundaries of the vertex and fragment shader stages, and both must be present for the shader to compile successfully. This requirement is closely related to the rule that both vertex and fragment stages are mandatory (see [Required shader stages](#required-shader-stages)). Other `#pragma` directives, such as `#pragma name`, `#pragma format`, and `#pragma parameter`, are optional and only need to be included if their functionality is desired. If omitted, their associated features will not be available, but the shader will still compile as long as the required stage pragmas are present. ### User parameter support Since we already have a "preprocessor" of sorts, we can also trivially extend this idea with user parameters. In the shader source we can specify which uniform inputs are user controlled, GUI visible name, their effective range, etc. #### Parameter Declaration, Validation, and UI Behavior When a `#pragma parameter` line is declared in a shader, the libretro frontend uses the information in the line to create a parameter entry in the user interface. Each entry displays the description, the current value, and the minimum and maximum values. Entries are populated in the order they appear in the shader source, and in the order of shader compilation (earlier passes compile first). The compiler validates each `#pragma parameter` line to ensure it is complete and well-formed. The step parameter is optional, but best practice is to always include it for clarity and consistency. If duplicate parameter lines are present—either due to an `#include` or because multiple shader passes declare the same parameter—the compiler checks that all lines for a given parameter name match exactly. This means that parameter lines using the same variable name must have identical descriptions, default values, minimum and maximum values, and step sizes across all declarations. If there is a mismatch, compilation will fail. In the RetroArch interface, parameter values are displayed to two decimal digits. However, the step size can be smaller than 0.01. If the step size is too small, users may not see the value change in the interface. Therefore, it is best practice to scale parameter values so that the step size is no smaller than 0.01 for optimal usability. ##### Examples **Simple Example:** ```glsl #pragma parameter Brightness "Screen brightness" 1.0 0.0 2.0 0.05 ``` This creates a parameter named `Brightness` with a description, default value, minimum, maximum, and step size. **Multiple Files Example A (Valid):** File 1: ```glsl #pragma parameter Sharpness "Sharpness level" 1.0 0.0 2.0 0.1 ``` File 2: ```glsl #pragma parameter Contrast "Contrast adjustment" 1.0 0.5 1.5 0.05 ``` These files declare completely different parameters. This is valid. **Multiple Files Example B (Valid):** File 1: ```glsl #pragma parameter Gamma "Gamma correction" 1.0 0.5 2.0 0.1 ``` File 2: ```glsl #pragma parameter Gamma "Gamma correction" 1.0 0.5 2.0 0.1 ``` These files declare the same parameter with identical lines. This is valid. **Multiple Files Example C (Invalid):** File 1: ```glsl #pragma parameter Saturation "Saturation adjustment" 1.0 0.0 2.0 0.1 ``` File 2: ```glsl #pragma parameter Saturation "Saturation level" 1.2 0.0 2.0 0.1 ``` These files declare the same parameter name (`Saturation`) but with different descriptions and default values. This will not compile; all fields must match exactly. **Note:** Validation is case sensitive. Parameter names, descriptions, and all values must match exactly, including letter case, for duplicate parameters across files or shader passes. ### Lookup textures A handy feature to have is reading from lookup textures. Custom sampler uniforms are specified in the `.slangp` (preset) file using the `textures` line, where values are separated by semicolons: ```ini textures = "foo;bar" ``` Each listed texture uniform can then be assigned a texture file and options: ```ini foo = "relative/or/absolute/path/filename.png" bar = "another_texture.png" ``` PNG and JPEG formats are known to be supported. Additional options can be set for each texture uniform: - `foo_linear = true` or `false` (enables or disables bilinear sampling; corresponds to shader option `filter_linearN`) - `foo_wrap_mode = clamp_to_edge` or other valid wrap mode strings (corresponds to shader option `wrap_modeN`) - `foo_mipmap = true` or `false` (enables or disables mipmapping; corresponds to shader option `mipmap_inputN`) Option values are case sensitive. Valid boolean values are `true` and `false`. It's recommended to enable mipmapping if your texture is simply going to be composited on screen (whether to mipmap LUTs warrants its own discussion entirely). This mechanism allows shader authors to bind custom textures to uniforms and control their sampling behavior and wrapping modes directly from the preset file, providing flexibility for advanced shader effects. For more information on the uniforms and aliases automatically provided when using lookup textures, see the [Aliases](#aliases) section. **Shader Example:** To use a custom texture declared in the preset file, declare the sampler uniform in your shader code: ```glsl #pragma stage fragment ... layout(binding = 2) uniform sampler2D foo; ``` Then, sample from the texture in your shader: ```glsl vec4 texColor = texture(foo, vTexCoord); ``` This will use the texture file and options specified for `foo` in the preset file. The binding number must match the preset's texture order. Explicit binding is mandatory for all samplers and UBOs. `sampler2D` objects can only be declared in the fragment shader stage. ## Slang specification This part of the spec considers how Vulkan GLSL shaders are written. The frontend uses the glslang frontend to compile GLSL sources. This ensures that we do not end up with vendor-specific extensions. The `#version` string should be as recent as possible, e.g. `#version 450` or `#version 310 es`. It is recommended to use `310 es` since it allows `mediump` which can help on mobile. !!! Note After the Vulkan GLSL is turned into SPIR-V, the original `#version` string does not matter anymore. !!! Warning SPIR-V cannot be generated from legacy shader versions such as `#version 100` (ES 2.0) or `#version 120` (GL 2.1). The frontend will use reflection on the resulting SPIR-V file in order to deduce what each element in the UBO or what each texture means. The main types of data passed to shaders are read-only and can be classified as: - `uniform sampler2D`: This is used for input textures, framebuffer results and lookup-textures. - `uniform Block { };`: This is used for any constant data which is passed to the shader. - `layout(push_constant) uniform Push {} name;`: This is used for any push constant data which is passed to the shader. ### Resource usage rules Certain rules must be adhered to in order to make it easier for the frontend to dynamically set up bindings to resources. - All resources must be using descriptor set `#0`, or don't use `layout(set = #N)` at all. - `layout(binding = #N)` must be declared for all `UBO`s and `sampler2D`s. - All resources must use different bindings. - There can be only one UBO. - There can be only one push constant block. - It is possible to have one UBO and one push constant block. - If a UBO is used in both vertex and fragment, their binding number must match. - If a UBO is used in both vertex and fragment, members with the same name must have the same offset/binary interface. This problem is easily avoided by having the same UBO visible to both vertex and fragment as "common" code. - If a push constant block is used in both vertex and fragment, members with the same name must have the same offset/binary interface. - `sampler2D` cannot be used in vertex, although the size parameters of samplers can be used in vertex. - Other resource types such as SSBOs, images, atomic counters, etc, etc, are not allowed. - Every member of the UBOs and push constant blocks as well as every texture must be meaningful to the frontend in some way, or an error is generated. ### Initial pre-process of slang files The very first line of a `.slang` file must contain a `#version` statement. The first process which takes place is dealing with `#include` statements. A slang file is preprocessed by scanning through the slang and resolving all `#include` statements. **Include Path Restrictions:** - Only files in the same directory as the including file, or in a child directory, may be included. Absolute paths and parent-relative paths (e.g., `../`) are not supported and have undefined behavior. **Cyclic Includes:** - Cyclic includes are not handled at all. If a file is included more than once in a dependency cycle, only the first occurrence is processed; subsequent `#include` lines for that file lead to undefined behavior. As a result, slang requires a flat, acyclic dependency structure for includes. The include process does not consider any preprocessor defines or conditional expressions. Nested includes are allowed as long as they do not form a cycle. This means `#include` handling does not respect `#ifdef`, `#ifndef`, `#if`, or similar conditional blocks. Even if an include appears inside a branch that would normally be compiled out by the GLSL preprocessor, slang still sees and processes that include during its own preprocessing step. For example, this is unintuitive but important: ```glsl #ifdef USE_OPTIONAL_HELPERS #include "optional-helper.inc" #pragma parameter DebugAmount "Debug Amount" 0.0 0.0 1.0 0.1 #endif ``` Even when `USE_OPTIONAL_HELPERS` is not defined, slang will still attempt to process the `#include` and will still discover the `#pragma parameter` line. In other words, these constructs are not conditionally skipped just because they appear inside a conditional GLSL block. E.g.: ```glsl #include "common.inc" ``` If a shader wants to reuse helper code when present but still compile when the file is missing, it can use an optional include pragma. #### `#pragma include_optional` This pragma behaves like `#include`, but does not generate an error if the specified file cannot be found. The format is: ```glsl #pragma include_optional "path/to/file_to_include" ``` This is useful for optional compatibility shims, shared parameter blocks, or helper files that may exist in one shader pack but not another. After includes have been resolved, the frontend scans through all lines of the shader and considers `#pragma` statements. These pragmas build up ancillary reflection information and otherwise meaningful metadata. Like includes, pragmas are discovered by scanning the source directly and do not respect `#ifdef` or related conditional compilation blocks. In practice, a pragma written inside a conditional block should still be treated as present by the slang frontend. #### `#pragma stage` This pragma controls which part of a `.slang` file are visible to certain shader stages. Currently, two variants of this pragma are supported: - `#pragma stage vertex` - `#pragma stage fragment` If no `#pragma stage` has been encountered yet, lines of code in a shader belong to all shader stages. If a `#pragma stage` statement has been encountered, that stage is considered active, and the following lines of shader code will only be used when building source for that particular shader stage. A new `#pragma stage` can override which stage is active. #### `#pragma name` This pragma lets a shader set its identifier. This identifier can be used to create simple aliases for other passes. E.g.: ```glsl #pragma name HorizontalPass ``` #### `#pragma alias` This pragma is supported as an alias of `#pragma name`. It sets the same shader identifier and has the same behavior as `#pragma name`. E.g.: ```glsl #pragma alias HorizontalPass ``` For consistency and clarity, `#pragma name` should be preferred in new shaders and documentation. #### `#pragma format` This pragma controls the format of the framebuffer which this shader will render to. The default render target format is `R8G8B8A8_UNORM`. Supported render target formats are listed below. From a portability perspective, please be aware that GLES2 has abysmal render target format support, and GLES3/GL3 may have restricted floating point render target support. ##### Portability Limitations: Guaranteed Formats **GLES2 (OpenGL ES 2.0):** The following framebuffer color formats are guaranteed to be supported on all GLES2-compliant devices (at least, according to specification): - `GL_RGBA4` - `GL_RGB5_A1` - `GL_RGB565` Other formats, such as `GL_RGBA8` or floating-point formats, are not guaranteed and may not be available on all GLES2 implementations. Unfortunately, none of these formats align with the formats that can be expressed by the pragma. **GLES3 (OpenGL ES 3.0):** GLES3 expands the set of guaranteed framebuffer formats. The following are required by the specification: - `GL_RGBA4` - `GL_RGB5_A1` - `GL_RGB565` - `GL_RGBA8` (corresponds to `R8G8B8A8_UNORM` with 8 bits per channel) - `GL_RGB8` - `GL_RGBA16` - `GL_RGB10_A2` (corresponds to `A2B10G10R10_UNORM_PACK32` with 10 bits per color channel, 2 bits per alpha) - `GL_R11F_G11F_B10F` - `GL_RGB10_A2UI` (corresponds to `A2B10G10R10_UINT_PACK32` with 10 bits per color channel, 2 bits per alpha) - `GL_RGBA16F` (corresponds to `R16G16B16A16_SFLOAT` with 16 bits per channel) - `GL_RGBA32F` (corresponds to `R32G32B32A32_SFLOAT` with 32 bits per channel) Desktop-oriented APIs can generally support all formats available. ##### Valid Formats **8-bit** - `R8_UNORM` - `R8_UINT` - `R8_SINT` - `R8G8_UNORM` - `R8G8_UINT` - `R8G8_SINT` - `R8G8B8A8_UNORM` - `R8G8B8A8_UINT` - `R8G8B8A8_SINT` - `R8G8B8A8_SRGB` **10-bit** - `A2B10G10R10_UNORM_PACK32` - `A2B10G10R10_UINT_PACK32` **16-bit** - `R16_UINT` - `R16_SINT` - `R16_SFLOAT` - `R16G16_UINT` - `R16G16_SINT` - `R16G16_SFLOAT` - `R16G16B16A16_UINT` - `R16G16B16A16_SINT` - `R16G16B16A16_SFLOAT` **32-bit** - `R32_UINT` - `R32_SINT` - `R32_SFLOAT` - `R32G32_UINT` - `R32G32_SINT` - `R32G32_SFLOAT` - `R32G32B32A32_UINT` - `R32G32B32A32_SINT` - `R32G32B32A32_SFLOAT` E.g.: ```glsl #pragma format R16_SFLOAT ``` If rendering to uint/int formats, make sure your fragment shader output target is uint/int. ##### Practical Format Choice Guidance When choosing a framebuffer format for your shader, consider the following practical recommendations: - For shaders that output gamma-corrected SDR (standard dynamic range) data, use `R8G8B8A8_UNORM` or simply omit the format specification (the default is usually suitable). - For shaders that output HDR10 data, any output intended for 10-bit display, or gamma-corrected intermediates requiring extra precision, use `A2B10G10R10_UNORM_PACK32`. - For shaders that output linear data (such as for realistic color blending or physically-based rendering), use `R16G16B16A16_SFLOAT`. - If your shader only needs to output one or two color channels, the `Rxx` or `RxxGxx` formats (e.g., `R16_UINT`, `R8_UNORM`) can be used for efficiency. Be aware that using higher bit-depth formats (such as 16-bit or 32-bit float) can have a significant impact on performance, especially on mobile or older hardware. Always profile your shader if performance is a concern. ##### Output transfer-function mapping When the final pass in a filter chain targets an HDR-capable display, the frontend selects a swapchain format that matches the display's capabilities. The transfer function the shader is expected to produce in its output depends entirely on which format the final pass renders to. Intermediate passes are not affected by these rules — only the last pass that writes to the swapchain. The table below summarises the contract for each relevant final-pass format. | Final pass format | Bit depth | Color space | Expected transfer function | Notes | |---|---|---|---|---| | `R8G8B8A8_UNORM` | 8-bit | Rec. 709 | Gamma-corrected (sRGB/Rec. 709) | SDR output. Gamma-corrected values can be written directly. Linear values must be gamma-corrected before output. Apply tone-mapping as needed before the final pass. | | `R16G16B16A16_SFLOAT` | 16-bit | Rec. 709 | Linear (scRGB) | HDR output via scRGB. Linear values can be written directly. Values above 1.0 represent luminance above SDR white. Gamma-corrected values must be linearized before output. PQ-encoded values must be linearized before output. | | `A2B10G10R10_UNORM_PACK32` | 10-bit | Rec. 2020 | PQ (ST 2084) | HDR10 output. HDR10-encoded (PQ) values can be written directly. Linear values, gamma-corrected values, and HLG values must all be converted to PQ before output. | ##### 8-bit output (`R8G8B8A8_UNORM`): SDR, Rec. 709 This is the standard SDR path. The display and the OS compositor both assume the output is gamma-corrected sRGB / gamma 2.2 in the Rec. 709 color space. - **Gamma-corrected values** can be written to `FragColor` directly. - **Linear values** must be gamma-corrected before output (apply inverse EOTF for the selected SDR display model). - **Tone-mapping** should be applied before the final pass whenever scene luminance can exceed the SDR range. ##### 16-bit output (`R16G16B16A16_SFLOAT`): scRGB, Rec. 709 scRGB is a linear, extended-range encoding in the Rec. 709 color space. The value `1.0` corresponds to the SDR white point (80 nits by convention). Values above `1.0` are legal and represent luminance above SDR white, up to the display's peak luminance. - **Linear values** can be written to `FragColor` directly. - **Gamma-corrected values** must be linearized before output. - **PQ-encoded values** must be linearized (apply the PQ EOTF) before output. ##### 10-bit output (`A2B10G10R10_UNORM_PACK32`): HDR10, Rec. 2020 HDR10 uses the PQ (ST 2084) transfer function in the Rec. 2020 color space. The PQ curve encodes an absolute luminance range of 0–10 000 nits, with `1.0` mapping to 10 000 nits. SDR white can correspond to either 100 nits or 203 nits. - **HDR10-encoded (PQ) values** can be written to `FragColor` directly. - **Linear values** must be converted to PQ encoding before output, including a gamut conversion from Rec. 709 to Rec. 2020 if the working color space is Rec. 709. - **Gamma-corrected values** must be linearized first, then converted to PQ as above. - **HLG-encoded values** must be converted to PQ before output (convert HLG → linear → PQ). #### `#pragma parameter` Shader parameters allow shaders to take user-defined inputs as uniform values. This makes shaders more configurable. The format is: ```glsl #pragma parameter IDENTIFIER "DESCRIPTION" INITIAL MINIMUM MAXIMUM [STEP] ``` The step parameter is optional. However, best practice is to always include the step parameter for clarity and consistency, even if the value is not strictly required. `INITIAL`, `MINIMUM`, and `MAXIMUM` are floating point values. `IDENTIFIER` is the meaningful string which is the name of the uniform which will be used in a UBO or push constant block. `DESCRIPTION` is a string which is human readable representation of IDENTIFIER. E.g: ```glsl layout(push_constant) uniform Push { float DummyVariable; } registers; #pragma parameter DummyVariable "This is a dummy variable" 1.0 0.2 2.0 0.1 ``` ### I/O interface variables The slang shader spec specifies two vertex inputs and one fragment output. Varyings between vertex and fragment shaders are user-defined. #### Vertex inputs Two attributes are provided and must be present in a shader. It is only the layout(location = #N) which is actually significant. The particular names of input and output variables are ignored, but should be consistent for readability. ##### `layout(location = 0) in vec4 Position;` This attribute is a 2D position in the form `vec4(x, y, 0.0, 1.0);`. Shaders should not try to extract meaning from the x, y. `gl_Position` must be assigned as: ```glsl gl_Position = MVP * Position; ``` ##### `layout(location = 1) in vec2 TexCoord;` The texture coordinate is semantically such that `(0.0, 0.0)` is top-left and `(1.0, 1.0)` is bottom right. If TexCoord is passed to a varying unmodified, the interpolated varying will be `uv = 0.5 / OutputSize` when rendering the upper left pixel as expected and `uv = 1.0 - 0.5 / OutputSize` when rendering the bottom-right pixel. #### Vertex/Fragment interface Vertex outputs and fragment inputs link by location, and not name. E.g.: ```glsl // Vertex layout(location = 0) out vec4 varying; // Fragment layout(location = 0) in vec4 some_other_name; ``` will still link fine, although using same names are encouraged for readability. #### Location allocation for composite types Location indices are consumed per slot, not per declaration line. Composite types can consume multiple consecutive locations. - Scalar and vector types (`float`, `vec2`, `vec3`, `vec4`, etc.) consume 1 location. - Matrix types consume multiple locations. A matrix consumes one location per column (for example, `mat4` consumes 4 locations). - Structs consume the sum of their members' location usage. - Non-matrix struct members consume 1 location each. - Matrix struct members consume one location per matrix column. Example (`mat4` consumes locations 0, 1, 2, and 3): ```glsl // Invalid: overlaps location 1, which is still part of CorrectionMatrix. layout(location = 0) in mat4 CorrectionMatrix; layout(location = 1) in float CorrectionScale; // Valid: next free location after mat4 is 4. layout(location = 0) in mat4 CorrectionMatrix; layout(location = 4) in float CorrectionScale; ``` When matching vertex outputs to fragment inputs, make sure both stages use compatible types and the same occupied location range. #### Fragment outputs ##### `layout(location = 0) out vec4 FragColor;` Fragment shaders must have a single output to `location = 0`. Multiple render targets are not allowed. The type of the output depends on the render target format. `int`/`uint` type must be used if `UINT`/`INT` render target formats are used; otherwise `float` type. ### Builtin variables #### Builtin texture variables The input of textures get their meaning from their name. - `Original`: This accesses the input of the filter chain, accessible from any pass. - `Source`: This accesses the input from previous shader pass, or `Original` if accessed in the first pass of the filter chain. - `OriginalHistory#`: This accesses the input # frames back in time. There is no limit on #, except larger numbers will consume more VRAM. `OriginalHistory0` is an alias for `Original`, `OriginalHistory1` is the previous frame and so on. - `PassOutput#`: This accesses the output from pass # in this frame. `PassOutput#` must be causal, it is an error to access `PassOutputN` in pass `M` if `N >= M`. `PassOutput#` will typically be aliased to a more readable value. - `PassFeedback#`: This accesses PassOutput# from the previous frame. Any pass can read the feedback of any feedback, since it is causal. `PassFeedback#` will typically be aliased to a more readable value. - `User#`: This accesses look-up textures. However, the direct use of `User#` is discouraged and should always be accessed via aliases. #### Builtin texture size uniform variables If a member of a UBO or a push constant block is called `???Size#` where `???#` is the name of a texture variable, that member must be a `vec4`, which will receive these values: - `X`: Horizontal size of texture - `Y`: Vertical size of texture - `Z`: `1.0` / (Horizontal size of texture) - `W`: `1.0` / (Vertical size of texture) It is valid to use a size variable without declaring the texture itself. This is useful for vertex shading. It is valid (although probably not useful) for a variable to be present in both a push constant block and a UBO block at the same time. #### Builtin uniform variables Other than uniforms related to textures, there are other special uniforms available. These builtin variables may be part of a UBO block and/or a push constant block. - `MVP`: `mat4` model view projection matrix. - `OutputSize`: a `vec4(x, y, 1.0 / x, 1.0 / y)` variable describing the render target size `(x, y)` for this pass. - `FinalViewportSize`: a `vec4(x, y, 1.0 / x, 1.0 / y)` variable describing the render target size for the final pass. Accessible from any pass. - `FrameCount`: an `uint` variable taking a value which increases by one every frame. This value could be pre-wrapped by modulo if specified in preset. This is useful for creating time-dependent effects. - `FrameDirection`: an `int` variable which indicates whether the content is currently being rewinded. Has a value of `-1` while rewinding, otherwise `1`. - `Rotation`: a `uint` variable with values from `0` to `3` describing the rotation of the content; respectively `0°`, `90°`, `180°`, and `270°`. - `OriginalAspect`: a `float` value describing the aspect ratio intended by the current core. - `OriginalAspectRotated`: a `float` value describing the intended aspect ratio after accounting for rotation. It is equal to `OriginalAspect` for unrotated and `180°`-rotated content, and `1.0 / OriginalAspect` for `90°` and `270°` rotation. - `OriginalFPS`: a `float` value describing the frame rate set by the core. - `FrameTimeDelta`: a `uint` value describing the time difference, in microseconds, between the previous and current frame. #### Checking for builtin uniform availability Some builtin uniforms were added after the initial slang implementation. If you want a shader to compile on older RetroArch versions, it is best practice to check whether newer builtin uniforms are available before using them. RetroArch provides the following preprocessor defines: - `_HAS_ORIGINALASPECT_UNIFORMS`: Indicates that `OriginalAspect` and `OriginalAspectRotated` are available. - `_HAS_FRAMETIME_UNIFORMS`: Indicates that `OriginalFPS` and `FrameTimeDelta` are available. For example: ```glsl #ifdef _HAS_FRAMETIME_UNIFORMS float deltaSeconds = float(FrameTimeDelta) * 1e-6; #else float deltaSeconds = 1.0 / 60.0; #endif ``` Using these defines lets a shader take advantage of newer runtime information while still remaining compatible with older frontend versions. #### Aliases Aliases can give meaning to arbitrary names in a slang file. This is mostly relevant for LUT textures, shader parameters and accessing other passes by name. If a shader pass has a `#pragma name NAME` associated with it, meaning is given to the shader: - `NAME` is a `sampler2D`. - `NAMESize` is a `vec4` size uniform associated with `NAME`. - `NAMEFeedback` is a `sampler2D` for the previous frame. - `NAMEFeedbackSize` is a `vec4` size uniform associated with `NAMEFeedback`. #### Example slang shader ```glsl #version 450 // 450 or 310 es are recommended layout(set = 0, binding = 0, std140) uniform UBO { mat4 MVP; vec4 SourceSize; // Not used here, but doesn't hurt float ColorMod; }; #pragma name StockShader #pragma format R8G8B8A8_UNORM #pragma parameter ColorMod "Color intensity" 1.0 0.1 2.0 0.1 #pragma stage vertex layout(location = 0) in vec4 Position; layout(location = 1) in vec2 TexCoord; layout(location = 0) out vec2 vTexCoord; void main() { gl_Position = MVP * Position; vTexCoord = TexCoord; } #pragma stage fragment layout(location = 0) in vec2 vTexCoord; layout(location = 0) out vec4 FragColor; layout(binding = 1) uniform sampler2D Source; void main() { FragColor = texture(Source, vTexCoord) * ColorMod; } ``` ### Push constants vs uniform blocks Push constants are fast-access uniform data which on some GPUs will improve performance over plain UBOs. It is encouraged to use push constant data as much as possible. ```glsl layout(push_constant) uniform Push { vec4 SourceSize; vec4 FinalViewportSize; } registers; ``` However, be aware that there is a limit to how large push constant blocks can be used. Vulkan puts a minimum required size of 128 bytes, which equals 8 `vec4`s. Using more than 128 bytes may lead to an error, so push constant blocks larger than 128 bytes should not be used. If you're running out of space, you can move the MVP to a UBO instead, which frees up 64 bytes. Always prioritize push constants for data used in fragment shaders as there are many more fragment threads than vertex. Also note that like UBOs, the push constant space is shared across vertex and fragment. E.g.: ```glsl layout(binding = 0, std140) uniform UBO { mat4 MVP; // Only used in vertex vec4 SpilledUniform; } global; layout(push_constant) uniform Push { vec4 SourceSize; vec4 BlurPassSize; // ... } registers; ``` ### Samplers Which samplers are used for textures are specified by the preset format. The sampler remains constant throughout the frame, and there is currently no way to select samplers on a frame-by-frame basis. This is mostly to make it possible to use the spec in GLES2 as GLES2 has no concept of separate samplers and images. ### sRGB The input to the filter chain is not presented as an sRGB texture. Likewise, the final pass does not render to an sRGB backbuffer by default. In practice, this means that shaders which need linear-light processing should perform explicit linearization themselves, usually in an early pass, and convert back to the desired output transfer function in a later pass. This approach also gives shader authors more control over gamma handling. For example, a preset can insert a pass which linearizes the source into a floating point render target, perform blending or lighting work in linear space, and then apply gamma correction before the final SDR output pass. For a more detailed framework covering how this applies to both SDR and HDR pipelines — including treating source content as virtual display signals, multi-pass HDR workflows, and practical pipeline examples — see [HDR Programming](#hdr-programming). ## Caveats ### Frag Coord TexCoord also replaces `gl_FragCoord`. Do not use `gl_FragCoord` as it doesn't consider the viewports correctly. If you need `gl_FragCoord` use `vTexCoord * OutputSize.xy` instead. ### Derivatives Be careful with derivatives of `vTexCoord`. The screen might have been rotated by the vertex shader, which will also rotate the derivatives, especially in the final pass which hits the backbuffer. However, derivatives are fortunately never really needed, since `w = 1` (we render flat 2D quads), which means derivatives of varyings are constant. You can do some trivial replacements which will be faster and more robust. ```glsl dFdx(vTexCoord) = vec2(OutputSize.z, 0.0); dFdy(vTexCoord) = vec2(0.0, OutputSize.w); fwidth(vTexCoord) = max(OutputSize.z, OutputSize.w); ``` To avoid issues with rotation or unexpected derivatives in case derivatives are really needed, off-screen passes will not have rotation and dFdx and dFdy will behave as expected. ### Correctly sampling textures A common mistake made by shaders is that they aren't careful enough about sampling textures correctly. There are three major cases to consider: | Bilinear sampling | If bilinear is used, it is always safe to sample a texture. | | Nearest, with integer scale | If the OutputSize / InputSize is integer, the interpolated vTexCoord will always fall inside the texel safely, so no special precautions have to be used. For very particular shaders which rely on nearest neighbor sampling, using integer scale to a framebuffer and upscaling that with more stable upscaling filters like bicubic for example is usually a great choice. | Nearest, with non-integer scale | Sometimes, it is necessary to upscale images to the backbuffer which have an arbitrary size. Bilinear is not always good enough here, so we must deal with a complicated case. If we interpolate `vTexCoord` over a frame with non-integer scale, it is possible that we end up just between two texels. Nearest neighbor will have to find a texel which is nearest, but there is no clear "nearest" texel. In this scenario, we end up having lots of failure cases which are typically observed as weird glitches in the image which change based on the resolution. To correctly sample nearest textures with non-integer scale, we must pre-quantize our texture coordinates. Here's a snippet which lets us safely sample a nearest filtered texture and emulate bilinear filtering. ```glsl vec2 uv = vTexCoord * global.SourceSize.xy - 0.5; // Shift by 0.5 since the texel sampling points are in the texel center. vec2 a = fract(uv); vec2 tex = (floor(uv) + 0.5) * global.SourceSize.zw; // Build a sampling point which is in the center of the texel. // Sample the bilinear footprint. vec4 t0 = textureLodOffset(Source, tex, 0.0, ivec2(0, 0)); vec4 t1 = textureLodOffset(Source, tex, 0.0, ivec2(1, 0)); vec4 t2 = textureLodOffset(Source, tex, 0.0, ivec2(0, 1)); vec4 t3 = textureLodOffset(Source, tex, 0.0, ivec2(1, 1)); // Bilinear filter. vec4 result = mix(mix(t0, t1, a.x), mix(t2, t3, a.x), a.y); ``` The concept of splitting up the integer texel along with the fractional texel helps us do arbitrary non-integer scaling safely. The uv variable could also be passed pre-computed from vertex to avoid the extra computation in fragment. See also [Advanced Techniques: Vertex Precomputation](#vertex-precomputation). ## Preset Format: Full .slangp Example The preset format is essentially unchanged from the old .cgp and .glslp, except the new preset format is called .slangp. Below is a comprehensive example of a `.slangp` preset file. This example demonstrates: - Multiple shader passes - Per-pass options (filter_linear, wrap_mode, scale_type, scale_x/y, mipmap_input, float_framebuffer, etc.) - External lookup textures with options - Parameter settings - Inline comments for clarity ```ini # Example: CRT with LUT and multi-pass scaling shaders = 3 # Pass 0: Horizontal blur shader0 = "shaders/blur_horiz.slang" filter_linear0 = true # Enable bilinear filtering for this pass wrap_mode0 = clamp_to_edge # Clamp sampling to edge scale_type0 = source # Scale relative to input scale_x0 = 2.0 # 2x horizontal scale scale_y0 = 1.0 # 1x vertical scale mipmap_input0 = false # No mipmapping on input float_framebuffer0 = false # Use integer framebuffer # Pass 1: Vertical blur shader1 = "shaders/blur_vert.slang" filter_linear1 = true wrap_mode1 = clamp_to_edge scale_type1 = absolute # Use absolute size scale_x1 = 1280 scale_y1 = 960 mipmap_input1 = false float_framebuffer1 = false # Pass 2: CRT effect with LUT shader2 = "shaders/crt.slang" filter_linear2 = false # Nearest neighbor for scanlines wrap_mode2 = clamp_to_border scale_type2 = viewport # Scale to viewport size scale_x2 = 1.0 scale_y2 = 1.0 mipmap_input2 = true # Enable mipmapping for LUT float_framebuffer2 = true # Use floating point framebuffer # External lookup textures textures = "phosphor_lut;mask" # LUT: Phosphor lookup table phosphor_lut = "textures/phosphor_lut.png" phosphor_lut_linear = true phosphor_lut_wrap_mode = repeat phosphor_lut_mipmap = true # Mask: Shadow mask pattern mask = "textures/mask.png" mask_linear = false mask_wrap_mode = mirrored_repeat mask_mipmap = false # Parameter overrides (optional, can be set in preset) Brightness = 1.2 Sharpness = 0.8 # Comments can be added anywhere with # # This preset demonstrates multiple passes, external textures, and parameter overrides. ``` This example shows how to: - Chain multiple shader passes, each with its own options - Bind external textures and control their sampling/wrapping - Override user parameters at the preset level - Use comments for documentation See the following sections for detailed explanations of each option and their effects. ## Porting guide from legacy Cg spec ### Common functions - mul(mat, vec) -> mat * vec - lerp() -> mix() - ddx() -> dFdx() - ddy() -> dFdy() - tex2D() -> texture() - frac() -> fract() ### Types - floatN -> vecN - boolN -> bvecN - intN -> ivecN - uintN -> uvecN - float4x4 -> mat4 ### Builtin uniforms and misc - modelViewProj -> MVP - IN.video\_size -> SourceSize.xy - IN.texture\_size -> SourceSize.xy (no POT shenanigans, so they are the same) - IN.output\_size -> OutputSize.xy - IN.frame\_count -> FrameCount (uint instead of float) - \*.tex\_coord -> TexCoord (no POT shenanigans, so they are all the same) - \*.lut\_tex\_coord -> TexCoord - ORIG -> `Original` - PASS# -> PassOutput# - PASSPREV# -> No direct analog, PassOutput(CurrentPass - #), but prefer aliases ### Cg semantics - POSITION -> gl\_Position - float2 texcoord : TEXCOORD0 -> layout(location = 1) in vec2 TexCoord; - float4 varying : TEXCOORD# -> layout(location = #) out vec4 varying; - uniform float4x4 modelViewProj -> uniform UBO { mat4 MVP; }; Output structs should be flattened into separate varyings. E.g. instead of ```cpp struct VertexData { float pos : POSITION; float4 tex0 : TEXCOORD0; float4 tex1 : TEXCOORD1; }; void main_vertex(out VertexData vout) { vout.pos = ...; vout.tex0 = ...; vout.tex1 = ...; } void main_fragment(in VertexData vout) { ... } ``` do this ```glsl #pragma stage vertex layout(location = 0) out vec4 tex0; layout(location = 1) out vec4 tex1; void main() { gl_Position = ...; tex0 = ...; tex1 = ...; } #pragma stage fragment layout(location = 0) in vec4 tex0; layout(location = 1) in vec4 tex1; void main() { } ``` Instead of returning a float4 from main\_fragment, have an output in fragment: ```glsl layout(location = 0) out vec4 FragColor; ``` ## FAQ for New Shader Developers The table below answers common first-time questions using only information already present in this document. | Question | Short answer from this document | References | |---|---|---| | What is the minimum valid `.slang` shader? | It must start with `#version` on the first line and define both `#pragma stage vertex` and `#pragma stage fragment`. | [Required Shader Stages](#required-shader-stages), [Initial pre-process of slang files](#initial-pre-process-of-slang-files) | | What are required vs optional pragmas? | Required: `#pragma stage vertex` and `#pragma stage fragment`. Others (for example `#pragma name`, `#pragma format`, `#pragma parameter`) are optional. | [#pragma directives: Required and Optional](#pragma-directives-required-and-optional), [Required Shader Stages](#required-shader-stages) | | Is vertex stage optional? | No. Both vertex and fragment stages are mandatory. | [Do we make vertex optional?](#do-we-make-vertex-optional), [Required Shader Stages](#required-shader-stages) | | How do includes work? | Includes are resolved in a pre-pass, do not respect `#ifdef` logic, and only support same-directory or child-directory paths. | [Initial pre-process of slang files](#initial-pre-process-of-slang-files) | | Can I include missing helper files safely? | Yes, use `#pragma include_optional "..."` to avoid a hard error if the file is missing. | [#pragma include_optional](#pragma-include_optional) | | What resource binding rules do I have to follow? | Explicit `layout(binding = N)` is required for samplers and UBOs; bindings must be unique; only one UBO and one push constant block are allowed. | [Resource usage rules](#resource-usage-rules) | | Can I use `sampler2D` in vertex shaders? | No. `sampler2D` is fragment-only, though texture size uniforms can be used in vertex. | [Resource usage rules](#resource-usage-rules) | | Which built-in textures and uniforms are available? | Built-ins include `Original`, `Source`, `PassOutput#`, `PassFeedback#`, and uniforms like `MVP`, `SourceSize`, `OutputSize`, `FrameCount`, and more. | [Builtin variables](#builtin-variables) | | How do I choose between push constants and UBOs? | Prefer push constants for frequently used data (especially fragment), but stay within the practical 128-byte limit; spill to UBO when needed. | [Push constants vs uniform blocks](#push-constants-vs-uniform-blocks) | | How should I choose render target format? | Use `R8G8B8A8_UNORM` for typical SDR, `A2B10G10R10_UNORM_PACK32` for HDR10/10-bit workflows, and `R16G16B16A16_SFLOAT` for linear-light processing. | [#pragma format](#pragma-format), [Practical Format Choice Guidance](#practical-format-choice-guidance) | | What wrap mode should I use by default? | Default is `clamp_to_border`; for compositing edges, `clamp_to_edge` is often safer. | [Texture Clamping and Wrap Modes](#texture-clamping-and-wrap-modes) | | Why do nearest-sampled shaders sometimes glitch at non-integer scale? | Interpolated UVs can fall between texels; pre-quantize coordinates to texel centers when doing nearest at non-integer scale. | [Correctly sampling textures](#correctly-sampling-textures) | | How do parameter declarations fail? | Duplicate `#pragma parameter` entries with the same identifier must match exactly (description and all numeric fields), or compilation fails. | [Parameter Declaration, Validation, and UI Behavior](#parameter-declaration-validation-and-ui-behavior), [#pragma parameter](#pragma-parameter) | | How do I add lookup textures in presets? | Declare them with `textures = "a;b"`, assign file paths per alias, then set optional per-texture options such as `_linear`, `_wrap_mode`, and `_mipmap`. | [Lookup textures](#lookup-textures), [Preset Format: Full .slangp Example](#preset-format-full-slangp-example) | | What is the recommended debugging workflow? | Start with RetroArch logs for compile errors, then use graphics debuggers/profilers (RenderDoc, Nsight, PIX, GPUView) and color-debug techniques. | [Validation, Debugging, and Profiling Tools for Slang Shaders](#validation-debugging-and-profiling-tools-for-slang-shaders), [Using the RetroArch Log for Shader Debugging](#using-the-retroarch-log-for-shader-debugging), [Debugging Shaders with Colors](#debugging-shaders-with-colors) | ## Advanced Techniques ### Validation, Debugging, and Profiling Tools for Slang Shaders #### Emulator Support and Reference Implementation Currently, there are no standalone external validation tools or compilers for slang shaders outside of RetroArch. However, other emulators such as Ares also support the slang format, though implementation details may differ and not all shaders are guaranteed to work identically across emulators. Some projects, like 86Box, have expressed interest in supporting slang shaders in the future. If you are an emulator developer and want to support slang shaders, you are encouraged to use RetroArch's MIT Licensed reference implementation. This ensures maximum compatibility and leverages the most mature and widely tested codebase for shader support among emulators. #### Note on Unrelated SLANG Formats There is a completely different SLANG format that was developed after RetroArch's. It is unrelated to Libretro and should not be confused with the slang shader format described in this document. #### Graphics Debugging and Profiling Tools While there are no slang-specific external tools, any graphics debugging or profiling tool that works with Vulkan, OpenGL, or Direct3D can be used to profile and debug slang shaders running in RetroArch. These tools allow you to inspect shader code, view intermediate render targets, analyze performance, and debug rendering issues. Some popular tools include: - **RenderDoc** (https://renderdoc.org/): - A powerful, open-source graphics debugger for Vulkan, OpenGL, and Direct3D. Capture a frame in RetroArch, inspect all draw calls, view shader code, and analyze textures and framebuffers. - **Getting started:** Launch RetroArch, start your content, and attach RenderDoc to the RetroArch process. Capture a frame and explore the pipeline and resources. - **NVIDIA Nsight Graphics** (https://developer.nvidia.com/nsight-graphics): - A comprehensive tool for debugging, profiling, and analyzing graphics applications on NVIDIA GPUs. Supports Vulkan, OpenGL, and Direct3D. - **Getting started:** Install Nsight Graphics, launch RetroArch through the tool, and use its frame debugging and profiling features. - **Microsoft PIX** (https://devblogs.microsoft.com/pix/): - A performance tuning and debugging tool for Direct3D applications on Windows. Useful for analyzing shaders and GPU workloads on D3D11/D3D12 backends. - **Getting started:** Run RetroArch under PIX, capture a frame, and inspect shader stages and GPU timings. - **GPUView** (https://docs.microsoft.com/en-us/windows-hardware/test/gpuview/): - A system-level GPU profiler for Windows, useful for analyzing overall GPU usage and identifying bottlenecks. These tools are invaluable for diagnosing rendering issues, optimizing performance, and understanding how your shaders interact with the graphics pipeline. #### Using the RetroArch Log for Shader Debugging RetroArch's log output provides some useful information for debugging shaders, especially compilation errors. If your shader fails to compile, check the log for detailed error messages, including the line number and nature of the error. You can increase the log verbosity in RetroArch's settings to get more detailed output. Reviewing the log is often the fastest way to identify and fix issues in your shader code. #### Debugging Shaders with Colors One of the simplest and most effective ways to debug shaders is to output specific colors in your fragment shader to "flag" certain conditions or code paths. This technique helps you visually identify when a particular branch of code is executed, when a value is out of range, or when a bug occurs. For example, you might want to check if a computed value exceeds a threshold, or if a texture coordinate is outside the expected range. By outputting a bright, easily recognizable color (such as red or green) when the condition is met, you can quickly spot issues on screen. **Example:** ```glsl #pragma stage fragment layout(location = 0) out vec4 FragColor; void main() { float value = ...; // Some computed value if (value > 1.0) { FragColor = vec4(1.0, 0.0, 0.0, 1.0); // Red: value is too high } else { FragColor = vec4(0.0, 1.0, 0.0, 1.0); // Green: value is OK } } ``` You can use this approach to test any condition—just pick a color that stands out. This visual feedback is especially useful when debugging complex effects, coordinate calculations, or sampling issues. Once you've identified and fixed the problem, simply remove or comment out the color-debugging code. Using the parameter system with this debugging technique can be very powerful. For example, parameters can be used as switches to bypass certain sections of code in real time, or to modify values meant for internal use. The parameters can be removed and the uniforms converted to constants before publishing. **Example: Using a Parameter as a Debug Switch** You can use a shader parameter to toggle debugging output on and off in real time. This allows you to enable visual debugging only when needed, without modifying the shader code each time. ```glsl #pragma parameter DebugMode "Enable debug color output" 0.0 0.0 1.0 1.0 layout(push_constant) uniform Push { float DebugMode; } registers; #pragma stage fragment layout(location = 0) out vec4 FragColor; void main() { float value = ...; // Some computed value if (registers.DebugMode > 0.5) { // Output bright green if debugging is enabled FragColor = vec4(0.0, 1.0, 0.0, 1.0); } else { // Normal rendering FragColor = ...; } } ``` This approach lets you toggle debug colors from the frontend UI, making it easy to test and diagnose issues interactively. You can add more parameters to control which conditions trigger debug output, or to adjust the debug color as needed. ### Naming Conventions for Uniforms and Samplers There are no strict requirements for naming or formatting uniforms and samplers in slang shaders—developers are free to choose conventions that best suit their project and style. However, here are some best practices and common patterns observed in the community: - **Samplers:** - Treat samplers just like any other variable. - External textures (such as lookup tables or fixed images) are often referenced with ALL_CAPS (e.g., `LUT`, `NOISE_TEXTURE`) to indicate that they are fixed, unchanging blobs. - Source textures, which change from frame to frame (such as `Source` or `Original`), are typically referenced with CamelCase to reflect their dynamic nature. - **Uniforms:** - Uniforms are fixed across a single frame but may change between frames. The uniforms presented by the frontend (such as `SourceSize`, `OutputSize`, `FrameCount`) use CamelCase for this reason. - Parameter uniforms (those controlled by the user or preset) are often considered 'fixed' and may be written in ALL_CAPS (e.g., `BRIGHTNESS`, `SATURATION`). - **#define Usage:** - It's common to use `#define` for uniforms that are referenced multiple times in a shader. This can improve readability and make it easier to update variable names in one place. - However, uniforms provided by the frontend (such as `SourceSize`, `OutputSize`, etc.) do not need to be `#define`d, as their names are stable and consistent for backwards compatibility. Ultimately, choose naming conventions that make your shader code clear and maintainable for yourself and others. Consistency within a project is more important than following any particular global style. If you are adding or modifying someone else's shader, it's best to follow the original style rather than refactoring the entire shader or mixing styles. ### Shader Version Selection and Cross-Platform Compilation When writing new slang shaders, always use `#version 450` unless you have a specific reason to use `#version 310 es` (for example, targeting mobile hardware that requires it). Using `#version 450` ensures broad compatibility with a wide set of features, and is the standard for Vulkan-based workflows. Only use `#version 310 es` if it is absolutely necessary for your use case. If you believe you need a newer shader version (such as `#version 460` or later), it's best to discuss your requirements with the Libretro developers first. There may be a workaround or alternative approach that will have better support across platforms. Users can be frustrated when they pick a shader that fails to compile on their system, so sticking to the most widely supported versions is recommended. #### Platform Differences and Testing Shader compilation and feature support can vary significantly between platforms, especially between Vulkan and DirectX. A shader that compiles and runs perfectly on Vulkan may not compile or behave the same way on DirectX (D3D11/D3D12), and vice-versa. For best results: - Always test your shader on Vulkan as a baseline, since it is the most robust and widely supported backend for slang shaders. - If you have access to a Windows system, also test your shader with at least one Direct3D driver (such as D3D12) to catch platform-specific issues early. - Be aware that some features or syntax may be accepted by one backend but not another. When in doubt, consult the documentation or ask the community for advice. #### Troubleshooting 'Unknown Semantic' Errors If shader compilation fails with an 'unknown semantic' error, check that every parameter uniform you declare in your shader has a matching `#pragma parameter` line. The reflection system relies on these lines to map uniforms to user parameters and internal semantics. Missing or mismatched pragmas are a common cause of this error. By following these guidelines, you'll maximize the portability and reliability of your shaders, and help ensure a smooth experience for users across all supported platforms. ### Best Practices for Multi-Pass (Multi-Stage) Shaders When designing shaders that are meant to be used together as a multi-pass (multi-stage) effect, following best practices for organization and clarity will help both you and other users maintain, extend, and reuse your work. It is common for users to group unrelated shaders into a custom preset, but for tightly coupled multi-pass effects, consider the following guidelines: 1. **Descriptive Naming:** - Give every shader a descriptive name using `#pragma name`. Avoid using numbers or generic names; prefer qualitative, meaningful names (e.g., `#pragma name GaussianBlurH` and `#pragma name GaussianBlurV`). - When shaders are meant to always be used together (tightly coupled), give them a matching prefix for clarity. 2. **Shared Functions:** - Place shared functions, macros, or utility code in a separate file with the `.inc` extension (not `.h`). Use `#include` to bring these into each shader file that needs them. 3. **One Stage per File:** - Do not try to put multiple fragment or vertex shaders in one file. Each `.slang` file can only have one vertex stage and one fragment stage. If for some reason a frontend ever supports this, ignore it. It's a bad idea. 4. **Shared Parameters:** - Use includes for parameters when they are shared among shaders. This ensures consistency and reduces duplication. Consider using the menu technique below to show users what shader stages or high-level aspects of the effect the parameters relate to. 5. **Document Pass Order:** - If the shader stages need to be used in a specific order, add a comment near the top of each file or in the preset to make this explicit. 6. **Example Preset File:** - Always include an example `.slangp` preset file showing how your multi-pass shader is intended to be used. - Assume that the input is gamma-corrected and the output is 8-bit SDR. If your shader operates on linear data, add a linearizing shader stage before and a gamma correction shader stage at the end. This makes it clear to users what sort of data your shader expects and produces. Following these practices will make your multi-pass shaders easier to understand, maintain, and integrate into larger filter chains or custom presets. ### Practical Guide to Feedback and History Feedback in slang shaders refers to the ability for a shader pass to access the output of a previous pass from the previous frame. This is a powerful technique for creating time-based effects such as motion blur, ghosting, persistence, and other temporal filters. #### What is Feedback? Each shader pass can declare a uniform sampler2D with the alias `NAMEFeedback`, where `NAME` is the pass name. The frontend (e.g., RetroArch) provides one frame of history for each `NAMEFeedback` uniform, following sensible best practice. This means you can access the output of a pass from the previous frame, but not from earlier frames directly. #### Why Use Feedback? Feedback enables effects that depend on previous frame data. Common uses include: - Motion blur - Temporal anti-aliasing - Persistence/afterglow - Ghosting - IIR (infinite impulse response) signal processing With just one frame of history, you can implement a wide variety of time-based effects using IIR techniques. By blending the current frame with the previous frame's output, you can achieve effects that appear to have "memory" or persistence, without needing multiple frames of history. #### How to Use Feedback 1. **Declare the Feedback Uniform:** - In your shader, declare a sampler2D uniform with the alias `NAMEFeedback`. - Example: ```glsl #pragma name BlurPass #pragma stage fragment layout(binding = 1) uniform sampler2D BlurPassFeedback; ``` 2. **Sample the Previous Frame:** - In your fragment shader, sample from the feedback texture. - Example: ```glsl vec4 prev = texture(BlurPassFeedback, vTexCoord); ``` 3. **Blend with Current Output:** - Combine the previous frame's output with the current computation to create a time-based effect. - Example (simple persistence): ```glsl FragColor = mix(texture(Source, vTexCoord), prev, 0.5); ``` #### Example: Temporal Persistence ```glsl #pragma name PersistencePass #pragma stage fragment layout(binding = 1) uniform sampler2D PersistencePassFeedback; layout(binding = 0) uniform sampler2D Source; layout(location = 0) in vec2 vTexCoord; layout(location = 0) out vec4 FragColor; void main() { vec4 current = texture(Source, vTexCoord); vec4 previous = texture(PersistencePassFeedback, vTexCoord); FragColor = mix(current, previous, 0.7); // 70% previous, 30% current } ``` #### Best Practices - Use feedback for effects that require temporal memory. - Limit feedback to one frame for performance and simplicity; frontends only provide one frame natively. - For more complex history (e.g., multi-frame effects), use additional passes to "shift" feedback manually, but this is rarely needed. - Leverage IIR signal processing techniques to achieve long-lasting effects with just one frame of history. #### Notes - Input textures can have arbitrary history (limited by memory), but cannot be fed back since the filter chain cannot render into them. - For the very first frames, feedback textures are initialized to transparent black (`0`). Feedback is a core feature for time-based shader effects, and mastering its use unlocks a wide range of creative possibilities. ### Vertex Precomputation In many cases, it is beneficial to perform certain calculations in the vertex shader and pass the results to the fragment shader as varyings. This technique, known as vertex precomputation, can improve performance by reducing redundant computations in the fragment shader, which typically runs many more times per frame than the vertex shader. #### Benefits - Reduces the computational load in the fragment shader, which is executed per-pixel. - Can help avoid redundant calculations, especially for values that are constant or linearly interpolated across a primitive. - May improve GPU throughput and efficiency, particularly on lower-end hardware. #### Example Suppose you need to compute a texture coordinate transformation that is the same for all fragments of a given vertex. Instead of repeating the calculation in the fragment shader, you can do it once in the vertex shader: ```glsl #pragma stage vertex layout(location = 0) in vec4 Position; layout(location = 1) in vec2 TexCoord; layout(location = 0) out vec2 vTransformedCoord; void main() { gl_Position = MVP * Position; // Example transformation vTransformedCoord = TexCoord * 2.0 + 0.5; } #pragma stage fragment layout(location = 0) in vec2 vTransformedCoord; layout(location = 0) out vec4 FragColor; void main() { FragColor = texture(Source, vTransformedCoord); } ``` #### Guidance - Use vertex precomputation for any value that is constant per vertex or can be linearly interpolated across the primitive. - Avoid duplicating expensive calculations in the fragment shader if they can be done once per vertex. - Be mindful that not all calculations are suitable for precomputation (e.g., those requiring per-pixel precision or non-linear interpolation). - Profile your shaders if in doubt; on complex scenes or low-power devices, the benefits can be significant. ### HDR Programming This section is informational best-practice guidance, not a strict prescription. The goal is to provide a conceptual framework that reduces avoidable errors by keeping HDR-related processes explicit and intentional. For background on how the slang pipeline handles gamma and linearization in general, see [sRGB](#srgb). Without explicit transfer-function and color-space discipline, advanced pipelines can produce luminance rolloff errors, highlight clipping/banding, hue shifts near gamut limits, and inconsistent results across SDR, scRGB, and HDR10 output paths. Structuring processing into explicit stages keeps each operation in a well-defined working space and isolates conversions so output-target or source-assumption changes can be handled predictably. To achieve this structure, we first must develop mental models for each of our stages. #### Signal model, linear light processing, and presentation The following is an example of how to break down a complex pipeline into stages using physical modeling. We'll start with three models: signal model, light model, and presentation model. Terminology is defined in [Pipeline vocabulary](#pipeline-vocabulary). ##### Stage 1: Real-world Signal Modeling As a working mental model, we can treat source texture data from a libretro core as normalized voltage video levels coming from a virtual DAC, video output connector, framebuffer, or other such device. A practical rationale for this choice: - Source values are often gamma-corrected signals, not linear-light scene data. - The source color space may not match modern presentation color spaces. - Applying display-like transforms too early or too late in the chain can introduce compounded errors. For this example, we'll operate on these assumptions: - Source data is in range [0, 1], mapping to lowest and highest signal voltages - Source data is gamma-corrected according to Rec. 601 - Source data represents the Rec. 601 color space, slightly different from target SDR color space (Rec. 709) and very different from target HDR color space (Rec. 2020) This model helps separate signal transport from light-domain math, and makes each conversion step intentional. We can do all signal-domain processes here. Other operations related to light blending or mapping to the user's color space have to be done after conversion steps. ##### Stage 2: Linear Light Processing Most physically meaningful operations (blending, bloom accumulation, blur energy conservation, and light-like compositing) are best behaved in linear light. General-purpose upscaling and downscaling algorithms are also usually best behaved in this stage because interpolation and reconstruction are performed in linear light. When blending is done in gamma-encoded domains, midtones and highlights are typically biased, causing dark seams, incorrect brightness rolloff, or halo artifacts. Converting to linear light before heavy compositing stages reduces these error sources and usually gives more stable results across backends. Output format is important at this stage. An 8-bit format can result in a loss of dynamic range, so 16-bit floating point format is recommended when shaders need to pass linear data to later shaders. This also allows values to exceed the [0, 1] range. ##### Stage 3: Presentation Presentation is the stage where linear working data is fit to an output-referred target. In practice, this mainly means: - tone mapping (compressing luminance into the target's usable range), and - gamut mapping/compression (fitting colors into the target primaries without severe clipping artifacts). Treat presentation as a deliberate final stage rather than something implied by format alone. This makes behavior easier to reason about when switching between SDR, scRGB, and HDR10 outputs. Presentation is where technical correctness becomes visible output behavior. Decisions made here primarily determine highlight rolloff, color fidelity near gamut boundaries, and consistency between SDR, scRGB, and HDR10 outputs. Practical guidance for Stage 3: - **Luminance anchoring**: Decide how internal linear values map to display-referred luminance before choosing tone mapping behavior. Keep this mapping explicit so the same shader behaves predictably across output targets. - **Tone mapping policy**: If linear-light values remain near the target range, simple clamping may be acceptable. If values significantly exceed target range, use a deliberate tone mapping operator to reduce hard clipping, highlight banding, and hue distortion. - **Gamut compression policy**: When targeting constrained or different primaries, use gamut compression to reduce clipping artifacts. Choose rendering intent based on artistic goal (for example, preserving relationships vs preserving in-gamut accuracy). - **Gamut compression intents**: The four classic ICC rendering intents are a useful frame of reference: - **Perceptual**: Compresses the full gamut to preserve visual relationships. - **Relative colorimetric**: Preserves in-gamut values and clips out-of-gamut values relative to target white. - **Saturation**: Prioritizes vividness over strict color accuracy. - **Absolute colorimetric**: Preserves absolute colorimetry including white-point differences, clipping out-of-gamut values. - **Output contract check**: Validate the final stage against the per-format output contract before shipping. The normative mapping for expected transfer function by final-pass format is [Output transfer-function mapping](#output-transfer-function-mapping) under [`#pragma format`](#pragma-format). - **Default operation order**: A stable baseline is tone mapping first, gamut compression second, then output encoding (inverse EOTF for SDR or PQ encoding for HDR). - **Validation checklist**: Verify neutral gradients stay neutral, highlight rolloff is smooth, saturated edges do not collapse abruptly, and behavior remains coherent when switching between SDR, scRGB, and HDR10 outputs. #### Transition Stages At this point, we have a model for a pipeline that looks like this: ```text Source -> Direct processing -> Linear light processing -> Tone mapping -> Gamut compression -> Output encoding ``` However, we haven't actually defined how we convert data from one stage to the next. For that, we need transition stages. SDR and HDR require separate paths. For unknown source characteristics, prefer a BT.1886 virtual display EOTF, which can be approximated as a simple 2.4 power function. For backlit handhelds, values near gamma 2.2 are often practical. For frontlit or reflective handhelds, treat the effective value as system-dependent. ##### SDR ```text Source -> Direct processing -> Virtual display EOTF -> Linear light processing -> Tone mapping -> Gamut compression -> SDR output (inverse EOTF) -> Output ``` ##### HDR ```text Source -> Direct processing -> Virtual display EOTF -> Linear light processing -> (Tone mapping) -> (Gamut compression) -> HDR output (PQ encoding) -> Output ``` HDR ranges are large, so tone mapping and gamut compression may not be necessary depending on the output range of the linear light processing stage. In this document, SDR output is described as inverse EOTF to emphasize preserving intended system-gamma behavior, rather than introducing a camera-style OETF model. HDR output is described as PQ encoding and requires mapping internal rendering values to intended nit values. #### Stage-to-workflow mapping The 3-stage model and the 6-step workflow describe the same process at different granularity. Use this crosswalk when moving from conceptual design to pass planning: | 3-stage model | 6-step workflow items | |---|---| | Stage 1: Real-world Signal Modeling | 1) Direct processing, 2) Virtual display EOTF | | Stage 2: Linear Light Processing | 3) Linear light processing | | Stage 3: Presentation | 4) Tone mapping, 5) Gamut compression, 6) Presentation encoding | #### Pipeline vocabulary The following terms are used throughout this section. - **Direct processing**: Operations applied directly to gamma-corrected source-domain signals. - **Virtual display EOTF**: A display-transfer model used to move source-domain signals into a linear-light working domain. - **Linear light processing**: Operations performed in linear light after applying the virtual display EOTF. - **Tone mapping**: Luminance remapping from working range into the target presentation range. - **Gamut compression**: Mapping of out-of-gamut colors into the target color volume with reduced clipping artifacts. - **SDR output (inverse EOTF)**: Final conversion from linear-light working values to SDR gamma-corrected output. - **HDR output (PQ encoding)**: Final conversion from linear-light working values to HDR10 PQ-encoded output. ##### Suggested workflow for complex pipelines Generalized summary: - Treat source values as signal-domain data first, then move intentionally into linear light through a virtual display EOTF. - Keep major reconstruction, filtering, compositing, and light-like operations in linear light for more stable and predictable results. - Use presentation controls (tone mapping and gamut compression) only when the target output or content range requires them. - Encode only at presentation: inverse EOTF for SDR, or PQ encoding for HDR10. Practical conclusion: Build presets so early and middle passes remain target-agnostic, then make the final presentation pass responsible for output encoding. This keeps SDR, scRGB, and HDR10 variants easier to maintain and less error-prone. Use a variety of test patterns to ensure color appearance behaves naturally. #### Example use cases The following examples show how the same process vocabulary can be applied to different shader goals. The pass names in these examples are conceptual placeholders; flexible implementation is left to developers. ##### Use case 1: Real-world model of a CRT device This pipeline follows all stages of the general flow. High-level outline: 1. **Direct processing**: Apply signal-domain operations that emulate source-side video behavior. 2. **Virtual display EOTF**: Linearize using a CRT-like display model (commonly BT.1886/approximate 2.4 behavior). 3. **Linear light processing**: Perform light-domain effects and compositing. 4. **Tone mapping**: Fit luminance into the output range. 5. **Gamut compression**: Compress out-of-gamut colors into the target primaries. 6. **Presentation encoding**: Use inverse EOTF for SDR targets or PQ encoding for HDR10 targets. Short `.slangp` example: ```ini shaders = 4 shader0 = "passes/composite_ntsc.slang" shader1 = "passes/virtual_display_eotf.slang" shader2 = "passes/crt_upscale_bloom.slang" shader3 = "passes/present_sdr_hdr.slang" # Example parameters (implementation-dependent) DisplayEOTF = 2.4 ToneMapStrength = 0.75 GamutCompress = 0.5 ``` ##### Use case 2: Real-world model of a reflective handheld device This pipeline is typically subtractive-only and often does not require tone mapping. However, gamut compression remains important because the device color appearance can differ strongly from typical modern monitors/TVs. Typical emphasis: 1. Apply direct/signal-domain shaping for handheld-like response. 2. Apply a handheld-appropriate virtual display EOTF. 3. Perform linear-light processing for stable compositing. 4. Skip tone mapping when dynamic-range expansion is not part of the goal. 5. Keep gamut compression as a primary presentation control. 6. Encode for final target (inverse EOTF for SDR or PQ encoding for HDR10). Short `.slangp` example: ```ini shaders = 4 shader0 = "passes/handheld_ghosting.slang" shader1 = "passes/handheld_linearize.slang" shader2 = "passes/handheld_dot_matrix.slang" shader3 = "passes/handheld_color_correct.slang" # Example parameters (implementation-dependent) DisplayEOTF = 2.2 GamutCompress = 0.8 ``` ##### Use case 3: Specialized upscaler A specialized upscaler usually does not require tone mapping or gamut compression as core stages, but interpolation/reconstruction should still be done in linear space for best behavior. Typical emphasis: 1. Optional direct processing for preconditioning. 2. Apply virtual display EOTF to reach linear light. 3. Run upscaler/reconstruction in linear light. 4. Skip tone mapping and gamut compression unless the preset's output target explicitly needs them. 5. Encode for presentation target (inverse EOTF for SDR or PQ encoding for HDR10). Short `.slangp` example: ```ini shaders = 3 shader0 = "passes/upscaler_linearize.slang" shader1 = "passes/upscaler_upscale.slang" shader2 = "passes/upscaler_present.slang" # Example parameters (implementation-dependent) DisplayEOTF = 2.4 ``` #### Common decision points | Question | Guidance | |---|---| | When should I include a tone mapping step? | Include it when working-space luminance values can fall outside the [0, 1] output range after processing. For small excursions, clamping is acceptable. For larger ones, use an explicit operator. Pure upscalers and linear pass-through chains typically skip this step. | | When does gamut compression matter most? | Gamut compression is most important when targeting sRGB / Rec. 709 output and when source content uses saturated colors that may extend outside Rec. 709. It is less critical for HDR or scRGB targets. | | Which virtual display EOTF should I use as a fallback? | Prefer BT.1886 (approximated as a 2.4 power function) when source characteristics are unknown. Use approximately 2.2 for backlit handhelds. Frontlit and reflective handhelds are system-dependent. | ## FAQ: Out of Scope for This Document This document is mainly about how to write and organize `.slang` shaders and `.slangp` presets. The questions below are the kind of things people often ask next, but they go beyond what this guide is trying to cover. | Out-of-scope question | Why it is out of scope here | |---|---| | What are practical varying/location limits per backend and GPU generation? | That depends a lot on the API, driver, and hardware you are running on. | | What is the exact precision policy (`mediump` vs `highp`) for each platform? | This guide does not try to lay down a per-platform precision policy. | | How are complex location packing edge cases handled (for example nested structs or arrays of structs)? | The basics are covered here, but not every GLSL packing corner case. | | What is the full runtime sampler binding order when built-ins, aliases, and user textures are mixed? | That gets into frontend/backend implementation details rather than shader authoring rules. | | Is there an official error-code catalog mapping compiler/runtime errors to fixes? | There is practical debugging advice here, but not a full backend-by-backend error reference. | | What pass-count/format budgets should be used for low-end hardware? | The document gives general performance advice, not hard budgeting targets. | | How much VRAM should be budgeted for deep history/feedback chains? | It explains the feature, but not exact memory budgeting. | | What are the exact guarantees during rapid resolution/aspect/rotation changes across all backends? | Those guarantees depend on backend behavior and are beyond this guide. | | What is the definitive precedence order between shader defaults, preset overrides, and runtime UI changes? | The pieces are described, but there is no formal precedence model spelled out here. | | Is there an official CI/validation workflow for shader pack maintainers? | This guide does not prescribe a standard CI or validation pipeline. | | What minimum cross-backend test matrix is required before release? | It recommends testing, but does not define a required release checklist. | ================================================ FILE: docs/development/shader/xml-shaders.md ================================================ # XML Shaders (Discontinued) !!! Warning XML shaders have been discontinued and are no longer available in RetroArch. This page should be considered only for historical reference. ## History XML shaders were originally implemented in bSNES as single pass GLSL shaders. The extension is `.shader` and is marked up with XML. These shaders were written against the fixed-function pipeline and is now referred to as a legacy XML shaders by RetroArch. The prefix ofruby originates from bSNES’ driver module, ruby::. ## Example legacy XML shader ``` ``` RetroArch implemented this legacy shader spec to be compatible with many shaders written at the time. It is also referred to as v1.0 XML shaders. This specification was then extended to support multi-pass, scaling arguments, etc, which resulted in v1.1 XML shaders (spec here). It is still legacy as it uses fixed-function features. RetroArch implements v1.1 XML shaders, and some more features to be feature equivalent with the Cg shader implementation. bSNES did not implement v1.1 and adoption of this spec was slowed down. ## Modern XML shaders Legacy XML shaders used fixed function, and they would therefore never work with modern GL (GLES, GL3.x+). To fix this, RetroArch extended the XML shader spec. Fixed function cruft like gl_ModelViewProjectionMatrix, gl_MultiTexCoord0 and gl_Vertex was replaced with uniforms and attribute streams. The modern XML shader spec in RetroArch focuses on being compatible with GLES2 (and compatible with GL 3.x+ as well). The ruby prefix was later deprecated and you could use TexCoord, VertexCoord etc. For compatibility reasons, the ruby prefix is still accepted. ## Example modern shader ``` ``` ## Moving off XML shaders XML shaders as a whole are deprecated in RetroArch, and will not be selectable in RGUI. You can still use them via video_shader config option. To use GLSL in RetroArch, the new GLSL shaders format is used, which mirrors the Cg shaders implementation quite well. The new GLSL shaders only support modern style, no fixed function. To convert XML shaders into straight GLSL, see GLSL shaders. ================================================ FILE: docs/googlea211139c43d4edca.html ================================================ google-site-verification: googlea211139c43d4edca.html ================================================ FILE: docs/guides/accessibility.md ================================================ # Accessibility ## What is Accessibility Accessibility features allow people with disabilities to access various types of software. In the case of RetroArch, the accessibility feature allows blind users to navigate the menus of RetroArch using the OS Narrator. Combined with the AI Service's Speech and Narrator modes, this can open up a large number of video games to blind players that couldn't play them beforehand. Windows, MacOS, and Linux are the supported platforms. ## How to enable Accessibility While Accessibility has been available in RetroArch since v1.8.2, it is turned off by default. One can turn it on from the in-RetroArch menu in one of two ways. For the XMB theme (default before v1.8.5) by pressing: right, up seven times, enter (or x on Linux), and then right, or for the Ozone theme (default v1.8.5 and later) by pressing: left, down, right, up seven times, enter (x on linux), and then right. Otherwise, running the RetroArch executable with the --accessibility flag will override the configuration setting, and turn on accessibility. For blind users, the command is as follows: "retroarch, space, two dashes, accessibility" For a complete guide on using Retroarch with accessibility features, see [This guide](retroarch-accessibility-guide.md) ## OS requirements RetroArch uses the OS narrator to speak out text. On Windows, this is the Microsoft Narrator, on MacOS, it is the "say" command, and on linux, it is the "espeak" command. If the narrator is not speaking any text, you can try installing the additional voice packs for your system language - [Windows voice install guide](https://support.microsoft.com/en-us/help/22805/windows-10-supported-narrator-languages-voices) - [MacOS voice install guide](https://support.apple.com/guide/mac-help/change-the-voice-your-mac-uses-to-speak-text-mchlp2290/mac) - On Ubuntu Linux, you can install espeak by running `sudo apt-get install espeak` in a terminal window, and `sudo apt-get install espeak-data` to install additional language voice packs. ## AI Service Text-to-Speech To use the AI Service with the Accessibility narrator, see the [AI Service doc page](ai-service.md). ================================================ FILE: docs/guides/ai-service.md ================================================ ## What is the AI Service This feature allows users to capture the current state of the game and feed it to a customizable endpoint for additional processing. With the help of OCR (optical character recognition) and other techniques, the AI service can provide a live translation of a game, or text-to-speech capabilities for the visually impaired among other things, either on demand or automatically. ## How it works When a user presses the AI Service hotkey, RetroArch will grab the screen of the game being played and send it to the service endpoint listed in the configuration. When the service returns, RetroArch will display the results according to the configuration. Pressing the AI Service hotkey again will clear any content currently displayed. ## How to set it up First, go to Settings->Input->Hotkey Binds, and assign a key for the AI Service. Next, go to Settings->AI Service and modify the configuration options as follows. `AI Service Enabled` should be set to `ON`. The `AI Service URL` is the URL of the AI service that you want to use. For example, `http://localhost:4404` for a service running locally on your computer and listening on port 4404. Check the documentation of the 3rd party AI service you're using to find out what this URL should be. (see "Known Services" below for some examples). `AI Service Output` controls how the processed content is displayed on your end. Naturally, your selection should match whatever capabilities the AI service you have configured offers. Note that `Image Mode` requires widgets to be enabled (Settings->On-Screen Display->On-Screen Notifications->Graphics Widgets). - In `Image Mode` the AI service is expected to return an image that will be overlaid on top of the game feed. This mode can be used to draw information on the screen, like writing a translation over the original text box. - In `Narrator Mode` the AI service is expected to return text that will be spoken on the user's machine using native text-to-speech capabilities, like the Windows narrator. - In `Speech Mode` the AI service is expected to return an audio file. This mode can be used as an alternative to the `Narrator Mode` if the user's machine is unable to use native text-to-speech, relying on the service to provide the actual audio. - In `Text Mode` the AI service is expected to return a text that will be displayed on top of the screen, like subtitles. - A combined mode like `Text + Narrator` works as you would expect, providing both the result as text on screen and text-to-speech. `Pause During Translation` will pause the core as soon as the user presses the AI Service hotkey and display whatever content is returned from the service. Pressing the AI Service hotkey a second time will clear the display and resume the core. `AI Service Text Position Override` can be used to control the placement of the subtitles on screen when `AI Service Output` is set to `Text Mode`. By default, services are able to control whether a specific subtitle should be displayed at the top or at the bottom of the screen depending on the situation. This setting however ignores the service hint and forces the placement to be one or the other, at the user's discretion. `AI Service Text Padding` allows a more precise control of the placement of the subtitle adding blank space at the bottom of the screen (for bottom-placed subtitles) or at the top of the screen (for top-placed subtitles). When the service is used to provide translation or text-to-speech using OCR, and `Source Language` is set to `Don't care`, the service will attempt to auto-detect the language on screen. Setting it to a specific language will increase accuracy, and restrict translation to only text in the source language specified. If `Target Language` is set to `Don't care` then the translation will be provided in English, or in the selected language otherwise. ## Automatic mode A special case must be made when the AI service needs to run automatically. By default, the AI service runs in a manual mode. The user presses the AI Service hotkey to process one screen immediately, receives the result, eventually presses the hotkey again to dismiss it and moves on before requesting the AI service once more. Some services however are able to run automatically. This can only be enabled by services themselves and is mostly designed for local services due to the high number of requests per second. If your service supports automatic mode, press the AI service hotkey once to enable processing. Now, the service will be polled at regular intervals and results will be automatically displayed as you keep playing. Pressing the AI service hotkey a second time (or invoking RetroArch's menu) will turn the AI service off. The `AI Service Auto-Polling Delay` option in the AI Service settings control how fast the automatic requests are sent to the service. If you are experiencing slowdowns during play, try increasing the delay. It will lower the reactivity of the AI service, but will lessen the load on your CPU. ## Known Services [VGTranslate](https://gitlab.com/spherebeaker/vgtranslate) is a python server you can run locally (or on your network) and uses Google Cloud OCR, and Google Text-to-Speech APIs with the Google Cloud keys you provide. [ZTranslate](https://ztranslate.net) uses a standalone client app for Windows or Linux that grabs the screen of the window currently in focus and displays a translated version in the ZTranslate client window. Also supports package-based translations for curated translations. [RetroArch-AI-with-IoTEdge](https://github.com/toolboc/RetroArch-AI-with-IoTEdge) uses IoTEdge and Azure Cognitive Services Containers (requires microsoft Azure account) to translate RetroArch screenshots and display them on a Lakka device. ## Supported Cores Since RetroArch v1.8.0, all cores should now be supported if your build has menu widgets. If not, then only software cores will be supported. ## For developers If you wish to implement your own AI service, here is what you need. RetroArch sends a POST request every time the user invokes the AI service, the URL params are as provided. - `source_lang` (optional): language code of the content currently running. - `target_lang` (optional): language of the content to return. - `output`: comma-separated list of formats that must be provided by the service. Also lists sub-formats supported by the current RetroArchBuild. The currently supported formats are: - `sound`: raw audio to play back. (`wav`) - `text`: text to be read through internal text-to-speech capabilities. `subs` can be specified on top of that to explain that we are looking for short text response in the manner of subtitles. - `image`: image to display on top of the video feed. (`bmp`, `png`, `png-a`) All in 24-bits BGR formats. In addition, the request contains a JSON payload, formatted as such: - `image`: captured frame from the currently running content (in base64). - `format`: format of the captured frame (`png`, or `bmp`). - `coords`: array describing the coordinates of the image within the viewport space (x, y, width, height). - `viewport`: array describing the size of the viewport (width, height). - `label`: a text string describing the content (`__`). - `state`: a JSON object describing the state of the frontend, containing: - `paused`: 1 if the content has been paused, 0 otherwise. - ``: the name of a retropad input, valued 1 if pressed. Values can be: a, b, x, y, l, r, l2, r2, l3, r3, up, down, left, right, start, select. The translation component then expects a response from the AI service in the form of a JSON payload, formatted as such: - `image`: base64 representation of an image in a supported format. - `sound`: base64 representation of a sound byte in a supported format. - `text`: results from the service as a string. - `text_position`: hint for the position of the text when the service is running in text mode (ie subtitles). Position is a number, 1 for Bottom or 2 for Top (defaults to bottom). - `press`: a list of retropad input to forcibly press. On top of the expected keys (cf. state, above) values `pause` and `unpause` can be specified to control the flow of the content. - `error`: any error encountered with the request. - `auto`: either `auto` or `continue` to control automatic requests. All fields are optional, but at least one of them must be present. If `error` is set, the error is shown to the user and everything else is ignored, even `auto` settings. With `auto` on `auto`, RetroArch will automatically send a new request (with a minimum delay enforced by ai_service_poll_delay); with a value of `continue`, RetroArch will ignore the returned content and skip to the next automatic request. This allows the service to specify that the returned content is the same as the one previously sent, so RetroArch does not need to update its display unless necessary. With `continue` the service *must* still send the content, as we may need to display it if the user paused the AI service for instance. ================================================ FILE: docs/guides/arcade-getting-started.md ================================================ # Getting started with arcade emulation Arcade emulation requires a different planning approach than console emulation. Arcade emulator terminology can also differ from the terms used in other kinds of emulation. ### Process The libretro core ecosystem includes a variety of arcade emulators, each with specific strengths and each requiring its own distinct version of arcade "romsets" which the emulator supports. Every arcade emulator core is optimized for different hardware and different games. This guide is intended to help you decide which core to use and find out what romset version is required for that emulator. You sometimes read people recommending to change core until your game works, this is extremely bad counselling for the following reasons : * It is usually faster to acquire/verify/rebuild romsets for a specific arcade core than to test each of your romsets with all available cores * You might be using an incomplete romset that is not playable in any core * Your platform might be missing the only core where that romset is playable * Some arcade cores are not recommended in most cases for reasons explained later in this document, so most users should avoid them * Retroarch playlists don't allow you to use a different core for each item, and you might not want to split your arcade games into several playlists The real recommended approach goes like this : 1. **Understanding the terminology** 2. **Choose an arcade emulator to match your system** 3. **Use the correct version romsets for that emulator** ![Arcade cabinets in an arcade room](../image/guides/arcade-emulation.png) --- ## Step 1: Understanding the terminology * **Arcade emulators**: Even more than consoles/computers, arcade machines had many manufacturers and generations since the first arcade machine back in 1971, hence why what we refer as "arcade emulators" are actually multi-system emulators able to emulate thousands of different systems at various levels of faithfulness. Note that while they are known for arcade emulation, they can also emulate consoles and computers. * **Dump**: A dump is the digital representation of 1 chip present on a game board/cartridge. * **Rom**: A rom refers to 1 file containing 1 single dump or several dumps concatenated together. * **Romset**: Literally "rom set", meaning a set of roms. A romset is an archive containing one or several individual rom(s), **arcade emulators expect this game format**. * **Romset version**: It's not unusual for a specific romset to exist in different versions. The reason for this is that sometimes the attempts at digitalizing chips failed, and instead of having a game totally unavailable due to a romset being only 90% complete, it was decided to implement workarounds in the emulator's code to make the game somehow playable. Every time one of those chips finally gets a proper dump, which can happen decades later, ongoing arcade emulators will update their code by removing the workarounds and loading the correct dump, hence why multiple romset versions can exist. * **Samples**: Sometimes, instead of emulating the sound coming from the actual board of a game, an emulator will use recorded sounds. There can be several reasons for this : the chips weren't dumped, the emulator doesn't emulate that sound board (yet), or the emulator allows as an alternative to replace that emulation by high quality sound coming from another source (OST, ...). * **CHD**: Some arcade games require data from an internal hard drive, CD-ROM, laserdisk, or other media in order to be emulated -- those forms of media are packaged as CHD files. CHD files should be copied to subfolders (going by the name of the romset) within the folder where the arcade romset has been installed. Additionally, there exist different kind of romsets : * **Bios romset**: A romset containing bioses required to run an arcade system. For example, the `neogeo` romset contains the bioses required to run SNK's NeoGeo cartridge system. * **Parent romset**: There can be multiple revisions of an arcade cabinet, the parent romset is usually the one dumped from the arcade cabinet which is believed to be the most recent revision, which is often a world or europe version. Parent romsets might require a bios romset to work. * **Clone romset**: Either dumped from arcade cabinet revisions believed to be older, or unofficial revisions of that arcade cabinet (bootlegs, hacks). Clone romsets might require a parent to work. * **Full non-merged romset**: The romset can be used standalone because the archive contains all the files required to run that romset, including any roms from its parent and bios romsets. * **Non-merged romset**: The romset can be used standalone because the archive contains all the files required to run that game, including any roms from its parent romset. With this format, a separate bios romset might be needed to run the romset. * **Split romset**: With this format, a clone romset never contains any of the roms present in its parent romset, and a parent romset never contains any of the roms present in its bios romset (if it exists). * **Merged romset**: Clones are merged into the parent romset zip, meaning that more than one game is stored in the romset. !!! info "ClrMamePro users" To rebuild Full Non-Merged romsets, use `Non-Merged` mode and deselect `Separate BIOS sets` via the `Advanced` button in the `Rebuild` and `Scanner` menus. ClrMamePro may display BIOS sets as missing in scans with these settings, but that is because all of the BIOS files will be distributed directly to the game romsets that need them. !!! tip "Recommended romsets" Non-merged romsets are recommended if you intend to use only a few romsets, while split romsets are recommended if you intend to keep the whole collection of romsets supported by an emulator. Merged romsets aren't recommended at all since [it's tricky](https://forums.libretro.com/t/how-to-play-clones-of-merged-mame-roms/35695) to run the alternate revisions of the game within the libretro ecosystem. --- ## Step 2: Choose an arcade emulator to match your system There are two families of multi-system arcade emulators available as libretro cores: FinalBurn and MAME. These emulators are in turn available in multiple versions to allow users to best match a core to their device. There are also a few console emulators that can alternatively emulate the arcade hardware based on that console. There is no "best arcade core", recommending one is hard without knowing your device and what you intend to play, each of them being differently balanced. ### The criterias for choosing an arcade core #### Integration within the libretro ecosystem A better integration allows for more features to be available from the frontend you are using, like netplay, runahead, rewind, retroachievements, ... but also reduces the risk of bugs. The quality of the integration is directly linked to the availability of a support team for the core. #### Accuracy Theoretically, more recent version of the emulators should always be more accurate, which means the graphics, sound and gameplay of the games are more likely to be faithful to the original cabinet. In reality, for vintaged MAME cores, with fixes being backported to some vintages and not some others, the situation is not so predictable. #### Input lag Accuracy improvements can add or remove frames of input lag. It is believed that **FinalBurn Neo** and **MAME (current)** have the lowest input lag on average. Also note that **FinalBurn Neo** has virtually 0 frames of input lag since it has full support for the runahead and pre-emptive frames feature. MAME also partially supports those features, with runahead second instance being recommended. #### Performance Being more accurate usually means the emulation will be more taxing on your cpu, so older versions of emulators will usually perform better at the cost of accuracy, and are worth trying if you have performance issues with more recent versions. Accuracy is not the only reason for performance regression though, the emulator framework has an impact too, this is especially noticeable on MAME which had its framework constantly updated over the years. #### Supported games Arcade emulators keep adding support for new machines over the years, so the more recent versions support more games. This is a double-edged sword as far as performance is concerned, because it can require updates to already emulated components, to add previously unemulated/unnecessary feature of the component, which might impact its emulation performance even for the machines that didn't need this feature. #### Emulator goal MAME's goal is to emulate every existing machines, including machines unrelated to gaming (it can emulate printers, vending machines, ...), the most accurately possible, while documenting them thoroughly. FinalBurn's goal is mainly to offer a comfortable experience for the end-user as a gaming software, and can include optional features that didn't exist on original cabinet (alternate controls for a better experience with modern controllers, alternate high-quality music, ...). MAME 2003-Plus has pretty much the same goal as FinalBurn, with both emulators actually sharing a few contributors. #### Support team Last but not least, most of the arcade cores have no real maintainer and are mostly there as a frozen-in-time alternative if the cores that have a support team can't play properly the game you want. **FinalBurn Neo** and **MAME 2003-Plus** have a support team (please note that MAME 2003-Plus is a hard fork which isn't written by the MAME team). **MAME (current)** gets regular bumps and has a regular maintainer to take care of issues related to its libretro integration. We don't recommend you try getting help from the MAME team for any of the MAME cores we provide, because you won't get any. ### Quick tour of every available core #### FinalBurn Neo * has the tightest integration within the libretro ecosystem * is mostly accurate, can be more accurate than MAME (current) on a few games * uses the latest known good romsets * is reasonably fast * has a support team * doesn't support 3D games, support fewer 2D games than MAME * keeps adding support for new games, including a lot of hacks and homebrews #### MAME 2003-Plus * while originally forked from MAME 2003, can be fairly accurate on some games since it incorporates some emulation fixes from recent versions of MAME * is quite fast, this fork was originally meant by the author to run on a pentium III @ 733mhz (Xbox OG) * doesn't have fixed romsets, doesn't always use latest known good romsets either * has a support team * supports a few classics that aren't supported yet in FinalBurn Neo * keeps adding support for new games #### MAME (current) * is usually the slowest core and the one that consumes the most memory * has a few dynamic recompilers for emulating more demanding systems, which can dramatically increase performance emulating those systems on supported cpus (x86_32, x86_64, and arm64 since 0.274) * is usually the most accurate * uses the latest known good romsets * has the widest range of emulated machines * keeps adding support for new games #### FinalBurn Alpha 2012 * has splitted cores for optimized memory usage if you are using a device with very very limited memory (wii, nds, ...) * has fixed romsets * is an older version of FinalBurn Neo, and as such should be faster while being less accurate and supporting less games, the libretro integration isn't as good either * should only be considered as an alternative on ultra low-power devices #### MAME 2000 * is the fastest arcade core * is the most inaccurate arcade core * has fixed romsets * has the smallest list of supported games * should only be considered as an alternative on ultra low-power devices #### MAME 2003 * is slower than MAME 2000 * is more accurate than MAME 2000 * has fixed romsets * support more games than MAME 2000 * probably shouldn't be used at all, MAME 2003-Plus is just plain better #### MAME 2010 * is slower than MAME 2003 * is more accurate than MAME 2003 * has fixed romsets * support more games than MAME 2003 * is missing support for basic libretro api features (savestates, ...) * probably shouldn't be used at all, most of the interesting things it has to offer were backported to MAME 2003-Plus, including lots of game additions #### MAME 2015 * is slower than MAME 2010 * is more accurate than MAME 2010 * has fixed romsets * support more games than MAME 2010 * is missing support for basic libretro api features (savestates, ...) * probably shouldn't be used at all, the performance gap with MAME (current) is usually small and can be in favor of the later, which also has a better libretro integration #### MAME 2016 * is slower than MAME 2015 * is more accurate than MAME 2015 * has fixed romsets * support more games than MAME 2015 * is missing support for basic libretro api features (rotation, ...) * probably shouldn't be used at all, the performance gap with MAME (current) is usually small and can be in favor of the later, which also has a better libretro integration #### Flycast * support arcade hardware based on Sega Dreamcast (NAOMI, NAOMI 2, AtomisWave and Sega System SP) * is the only working libretro core for those 4 systems #### Kronos * support arcade hardware based on Sega Saturn (ST-V) * MAME is also able to emulate ST-V #### DICE * supports machines without any type of CPU --- ## Step 3: Use the correct version romsets for that emulator The recommended format for arcade romsets is zip, it has the fastest loading and the widest support. 7zip might work or not. **If you extract an arcade romset, it won't work**. As previously said, arcade emulators emulate thousands of different machines, so they need a mean to identify which machine run a given romset, it was decided to use the archive's filename for this purpose. **If you rename an arcade romset, it won't work**. Each file within a romset is the dump of a chip with a specific purpose (program data, sound data, graphics data, ...), the emulator needs to identify each dump's role, it was decided to use their signature (crc) for this purpose (filenames can sometimes be used as a fallback to load bad/hacked dump). **If your romset doesn't contain the exact files the emulator requires, it won't work**. !!! Warning When using romsets for the latest version of MAME or FBNeo, you should first make sure your version of those cores aren't outdated. !!! tip In general, you will get better results with a full collection of romsets for your chosen emulator. Starting with individual arcade romsets is less likely to work because you generally won't know which emulator they target, or if they contain every required files to run the game (bios, parent). Full Non-Merged romsets are widely available for all of the "historic" MAME cores. **Full Non-Merged romsets are the simplest romset format to get started with because each romset archive contains all necessary files for emulating one game.** | Emulator | Required ROM Version | ClrMamePro dat file | | :---: | :---: | :---: | | DICE | DICE 0.3.0 | [here](https://github.com/mittonk/dice-libretro/blob/main/dice_xml.dat) | | FB Neo | FBNeo (latest version) | [here](https://github.com/libretro/FBNeo/blob/master/dats/FinalBurn%20Neo%20(ClrMame%20Pro%20XML%2C%20Arcade%20only).dat) | | FB Alpha 2012 | FBA 0.2.97.24 | N/A | | MAME 2000 | MAME 0.37b5 | [here](https://github.com/libretro/mame2000-libretro/blob/master/metadata/MAME%200.37b5%20XML.dat) | | MAME 2003 | MAME 0.78 | [here](https://github.com/libretro/mame2003-libretro/blob/master/metadata/mame2003.xml) | | MAME 2003-Plus | MAME 2003-Plus (latest version) | [here](https://github.com/libretro/mame2003-plus-libretro/blob/master/metadata/mame2003-plus.xml) | | MAME 2010 | MAME 0.139 | [here](https://github.com/libretro/mame2010-libretro/blob/master/metadata/mame2010.xml) | | MAME 2015 | MAME 0.160 | [here](https://github.com/libretro/mame2015-libretro/blob/master/metadata/mame2015-xml.zip) | | MAME 2016 | MAME 0.174 | [here](https://github.com/libretro/mame2016-libretro/blob/master/metadata/MAME%200.174%20Arcade%20XML%20DAT.zip) | | MAME (latest version) | MAME (latest version) | [here (click XML link)](https://www.mamedev.org/release.html) | ### Optional : ClrMamePro tutorial Clrmamepro is a tool to help validating your romsets against a given emulator. !!! info "Credits" This tutorial is based on RetroPie's #### Step 1 - Back up your ROMs It is possible with ClrMamePro to change one or two options and when it runs it will delete all your existing ROMs. OK, not really - using the default options it will make backups of any files it removes, but it is still possible to mess up their ROMs beyond repair when getting started with ClrMamePro. #### Step 2 - Download [ClrMamePro](http://mamedev.emulab.it/clrmamepro/#downloads) #### Step 3 - Acquire DAT files You can download most DAT files from above. #### Step 4 - Run ClrMamePro for the first time * Run it. The welcome screen explains that common first steps are to 1) Create a Profile, 2) Set up your paths and 3) Scan your ROMs. We will be doing things slightly differently, in order to leave your source ROMs intact. * Click OK to the Welcome screen * Click **"Add DatFile..."**, search and open the DAT file you downloaded * Accept the default profile location of [PROFILES], click **"OK"** * Select **"[NEW DATFILES]"** in the left-hand pane and select the one jou just added in the right-hand panel * Click **"Load / Update"** * ClrMamePro will ask you how to generate the settings for this datfile, click **"Default"** (it is possible it will throw a warning but just select **"ok to all"** and continue on) * You are now at the main window for clrmamepro. We still need to set our paths, so click **"Settings"** * Verify **"ROM-Paths"** is the selected option in the upper-left corner drop down menu * Click the **"Add..."** button * Create a folder where you'll store your romsets, select it and click **"OK"** * Close the settings window with the **"X"** button in the upper right At this point, you could scan the ROMs folder you just selected, but we just created this folder and it is empty. Instead, we will rebuild into this folder. #### Step 5 - Rebuild a ROM set * In the main ClrMamePro window, select **"Rebuilder"** * The destination should already be filled in for you - it is the same as the ROM path you defined above * Use the browse button **"..."** to select your source path. For example you might have a folder where you stored various arcade ROM sets you got from various sources - point ClrMamePro to that directory as your source. * When rebuilding there are three options: **Non-Merged, Merged, and Split**. Pick the one you prefer. If you select "Non-Merged" in this menu, it is recommended to click the "Advanced" button and deselect "Separate BIOS sets", so that ROM sets will also be self-sufficient with BIOS. * Click **"Rebuild..."**. Depending on the size of the directory you chose as a source, this could take some time * When ClrMamePro is finished rebuilding, you will see a window with statistics showing how many matching files were found, how many files were created and how many were skipped. Click "OK" * Repeat for any other source paths you might have. You can rebuild from multiple sources, but leave the Destination path the same * When finished, close the Rebuilder with the **"X"** in the upper right corner of the window Time to find out how well your source ROMs matched up... #### Step 6 - Scan a ROM set * In the main ClrMamePro window, select **"Scanner"** * Leave all settings at default and click **"New Scan..."** * When ClrMamePro finishes scanning, you will see a "Statistics" window with high level information and a "Scan Results" window with detailed information about your missing ROMs #### Notes * Typically you cannot completely 'roll forward' from an old ROM collection version to a new version, since these will often feature entirely new roms or dumps that weren't present in your older version. The same is true for 'rolling back' from a new version to an older version, but there are 'rollback' sets available that collect all the previously deleted ROMs from old versions that you can use to fill in the gaps. * Be careful with the "Fix" settings in the Scanner window and the "Remove Matched Sourcefiles" setting in the Rebuilder window. These settings will remove and rename your ROMs. * If ClrMamePro does delete any ROMs (because you told it to), you should be able to find backups in C:\clrmamepro\backup as long as you didn't change the default settings. * ClrMamePro is very stable. It has been around for a long time, it is regularly updated and it is widely used. If it reports problems reading your ROMs, you most likely have corrupt ROM archives (zip files) or a failing hard drive. * If you feel the need to reset ClrMamePro's settings, just delete your existing profile(s) and reload your DAT file, selecting **"Default"** settings for the new profile. Almost all of ClrMamePro's settings are per-profile. --- ### RetroArch Playlist Scanner Support ~~The RetroArch content database supports arcade romsets in Full Non-Merged and Split formats. In order to be recognized by the scanner, Full Non-Merged and Split romsets must also be [processed by TorrentZip to standardize their CRC](https://sourceforge.net/projects/trrntzip/).~~ Manual scan is the recommended method for setting up arcade playlists in RetroArch. [Here](https://neo-source.com/index.php?topic=3725.0) is a guide written for creating FBNeo playlists, but you can easily adapt it for MAME usage. !!! info "Credits" The arcade cabinets image is based on an image by Rob DiCaterino, licensed for reuse under a Creative Commons (CC BY 2.0) License. Original image and license: https://www.flickr.com/photos/goodrob13/17385639015/ ================================================ FILE: docs/guides/bios.md ================================================ # BIOS A BIOS file is a copy of the operating system used by the hardware that a Core is emulating. Some Cores need BIOS files in order to correctly emulate hardware and/or software as needed by the content. RetroArch and LibRetro do not share any copyrighted system files or game content. You must provide your own BIOS and content in accordance with your local laws as applicable. **Example** | Core |Required |Optional| |----------------|-------------------------------|-----------------------------| |[Beetle PSX HW](../library/beetle_psx_hw.md)|✔ | ✕ | |[mGBA](../library/mgba.md)|✕ |✔ | |SwanStation|✔|✕| |[PCSX ReArmed](../library/pcsx_rearmed.md)|✕ |✔ | ![Basic Workflow](https://cdn.discordapp.com/attachments/615183202239381544/757354372064739428/Workflow-Diagram.png) ## High-Level Emulation (HLE) High-Level Emulation (HLE) tries to reproduce the console's outputs instead of its actual behavior, though bugs and glitches are often common. ## Where do BIOS files go? Usually BIOS files go to RetroArch's "system" directory. Check settings --> directory and the core documentation to be sure. ================================================ FILE: docs/guides/building-lakka.md ================================================ # Building Lakka ___ Lakka is the official Linux distribution of RetroArch and the libretro ecosystem. Each game system is implemented as a libretro core, while the frontend RetroArch takes care of inputs and display. This clear separation ensures modularity and centralized configuration. Lakka is a lightweight Linux distribution that transforms a small computer into a full blown retrogaming console. | :warning: DISCLAIMER | |:---------------------------| | Lakka is still under heavy development. In its current state, the project allows you to play most games on most platforms. However, expect bugs, missing features or features not working as intended, and hardware that is yet to be supported. If you find a bug, you can declare it in our [tracker](https://github.com/libretro/Lakka-LibreELEC/issues), unless already reported. | ## Compiling Lakka ___ This page is for developers who want to customize their build and/or contribute to Lakka. You will need Linux (we usually build on Debian or Crux) and the base development packages (build-essential on Debian). You may also need a local HTTP server to host Lakka packages if you plan to do packaging. ### Building Lakka the first time First, clone Lakka? ```sh $ git clone https://github.com/libretro/Lakka-LibreELEC ``` Lakka is organized by projects, the Generic project targets PCs, while other projects like RPi targets very specific hardware like the Raspberry Pi. The full list of projects can be listed like this: ```sh $ ls -l Lakka-LibreELEC/projects ``` You can now launch make, set the PROJECT and ARCH variables to fit your needs: ```sh $ cd Lakka-LibreELEC $ DISTRO=Lakka PROJECT=RPi DEVICE=RPi ARCH=arm make image # for the Raspberry Pi $ DISTRO=Lakka PROJECT=RPi DEVICE=RPi2 ARCH=arm make image # for the Raspberry Pi2/ Pi3 $ DISTRO=Lakka PROJECT=RPi DEVICE=RPi4 ARCH=arm make image # for the Raspberry Pi4 (arm 32bit) $ DISTRO=Lakka PROJECT=RPi DEVICE=RPi4 ARCH=aarch64 make image # for the Raspberry Pi4 (arm 64bit) $ DISTRO=Lakka PROJECT=NXP DEVICE=imx6 ARCH=arm make image # for the Hummingboard and Cubox-i $ DISTRO=Lakka PROJECT=Generic ARCH=x86_64 make image # for 64 bits PCs $ DISTRO=Lakka PROJECT=Generic ARCH=i386 make image # for 32 bits PCs ``` Building Lakka the first time takes a lot of time, you can go grab a coffee or two :) If the build fails, make sure you have at least 10 GB of free space and try to figure out which package is missing, install it, and make again. You will find the result in Lakka-LibreELEC/target: ```sh $ ls -l target ``` The .kernel and .system can be used to upgrade an existing Lakka system. The .img.gz is the final result, it contains the image that can be flashed to an SD card or a USB pen drive. Please follow this [tutorial](http://www.lakka.tv/get) to know how to flash Lakka on a drive. ### Upgrading your Lakka build If some time passed and you want to rebuild from newer sources: ```sh $ cd Lakka-LibreELEC $ git pull $ rm -rf target $ DISTRO=Lakka PROJECT=RPi DEVICE=RPi ARCH=arm make image ``` But if you just want to rebuild a particular package, for example a package you are trying to port to Lakka, you can just remove it like this and rebuild. ```sh $ DISTRO=Lakka PROJECT=RPi DEVICE=RPi ARCH=arm scripts/clean yourpackage $ DISTRO=Lakka PROJECT=RPi DEVICE=RPi ARCH=arm scripts/build yourpackage ``` If you want to rebuild all from scratch, remove the build* folders ## Conclusion ___ Lakka is still under heavy development. In its current state, the project allows you to play most games on most platforms. More information can be found in the [Lakka documents](http://www.lakka.tv/doc/Home/). You may also want to check the [Official Forum](https://forums.libretro.com/c/libretro/lakka-tv-general). ================================================ FILE: docs/guides/building-ludo.md ================================================ # Building Ludo ___ Ludo is an Emulator Frontend able to run retro video games. Ludo does not emulate the consoles itself, but does it through emulator plugins called libretro cores. Libretro cores are well known emulators (like Snes9x or Genesis Plus GX or PCSX) stripped from their user interface. They contain only console specific logic. | :warning: DISCLAIMER | |:---------------------------| | Ludo is still under heavy development. In its current state, the project allows you to play most games on most platforms. However, expect bugs, missing features or features not working as intended, and hardware that is yet to be supported. If you find a bug, you can declare it in our [tracker](https://github.com/libretro/ludo/issues), unless already reported. | ## Prerequisites - GLFW 3.3 - OpenGL >= 2.1 - OpenAL ## Building ___ Building Ludo from source is for developers and contributors. ### Ubuntu and Debian ```sh sudo apt install git go libopenal-dev xorg-dev git clone --recursive https://github.com/libretro/ludo.git cd ludo go build ./ludo ``` ### Red Hat, CentOS and Fedora ```sh sudo yum install golang libopenal-soft-devel libX11-devel git clone --recursive https://github.com/libretro/ludo.git cd ludo go build ./ludo ``` ### Windows Setup [Git Bash](https://gitforwindows.org/) then setup [Go](https://golang.org/dl/). When you done with these setup [MinGW-w64](https://sourceforge.net/projects/mingw-w64/) and add it to your PATH. Download http://static.kivutar.me/openal-soft-1.19.0-bin.zip and extract it for example in C: Setup MinGW-w64 and add it to your PATH Download http://static.kivutar.me/openal-soft-1.19.0-bin.zip and extract it for example in C: ```shell export CGO_CFLAGS="-I/c/openal-soft-1.19.0-bin/include/" export CGO_LDFLAGS="-L/c/openal-soft-1.19.0-bin/build/Release/" ``` ```Powershell git clone --recursive https://github.com/libretro/ludo.git cd ludo go build ./ludo ``` ### Mac OS X First setup [Xcode](https://developer.apple.com/documentation/xcode/) then setup [Homebrew](https://brew.sh/). ```brew brew install go openal-soft git clone --recursive https://github.com/libretro/ludo.git cd ludo go build ./ludo ``` ================================================ FILE: docs/guides/change-directories.md ================================================ # Directory configuration Next step you might want to consider is setting directories for RetroArch, this can help get the best experience possible. Although the defaults will suit most users, if you want to configure custom BIOS's or change the save location, you will have to change directories. Some directory variable values are set to "default" by default in retroarch.cfg. However, to modify directory values to "default", a text editor is required. "default" represents different values to different entries in `Settings` -> `Directories`: - `` -- The directory where the game was loaded from via `Main Menu -> Load Content`. For example, if /home/gamer/Downloads/SNES/game.sfc was loaded, and retroarch.cfg contains `screenshot_directory = "default"`, then the screenshots will be saved in /home/gamer/Downloads/SNES/. - For multiple directory variables in retoarch.cfg, the "default" value sets their value in `Settings` -> `Directories` to:`` -- The RetroArch configuration directory. Table of special values limited to some variables: | retroarch.cfg configuration | RetroArch `Settings` -> `Directories` | | - | - | | system_directory = "default" | `System/BIOS`: `` | | screenshot_directory = "default" | `Screenshots`: `` | ## From RetroArch: - Open RetroArch. - Navigate to `Settings` -> `Directories`. - Click on the directory you want to change. - Navigate to the desired location using the File Browser. ## From a text editor: - Close RetroArch. - Find your retroarch.cfg file. If you are having trouble locating the file, 1) Open RetroArch 2) Navigate to `Main Menu` -> `Configuration File` -> `Save Current Configuration`, the on-screen notification widget will display: `Saved new config to "[...]/config/retroarch/retroarch.cfg".`. If all hope is lost do a system-wide search for **retroarch.cfg** - Open retroarch.cfg in a text editor. - After the = sign, make changes then save the file. # Paths to consider changing: ## Cores This is the location for all your cores. To [install them using the user interface](download-cores.md#installing-cores-through-retroarch-interface), this setting needs to point to a writeable directory. !!! note The Ubuntu PPA does not point this to a user-writable directory because cores are modified by the package manager. If you want to change it manually, you might want to change this directory from "retroarch.cfg" with a text editor since the RetroArch file browser doesn't show hidden folders by default. *libretro_directory =* is what you need to change in the config file. Some distributions use `~/.config/retroarch/cores/` ## System/BIOS This is where you specify the location for all your BIOS's, by default RetroArch looks for BIOS in your "Starting directory" folder. It is not suggested that you dump all BIOS files in the "Starting directory". !!! note Some emulators *(Example: PS1 and PSP)* will require BIOS files to even function. It is suggested that this be changed to a folder named "system" under your retroarch config folder. If you can't be bothered to try and find this config folder (since it varies from OS), and you want to skip having to use a text editor, choose another location that the BIOS files will be. !!! note You might want to change this directory from "retroarch.cfg" with a text editor since the RetroArch file browser doesn't show hidden folders by default. *system_directory =* is what you need to change in the config file. ## File Browser Another one you'll want to consider changing. This will be the starting directory when you select "Load Content" and it can be very handy to have this set to your ROM folder. Although this probably isn't needed since RetroArch has an import feature, it doesn't hurt to have this set anyway. ## Save Files, and Save States !!! note Some platforms/distros may use a different structure, so always verify your paths in settings -> directory Last one you should consider changing are the save locations, by default it will place them in the same folder as your ROMS. If you care about organisation you should change these to another folder. ================================================ FILE: docs/guides/cheat-codes.md ================================================ # RetroArch cheat and rumble codes RetroArch uses two methods of applying cheat codes: - **Emulator Handled** are codes that are sent to the emulator/core and it is up to the emulator/core to apply them. - **RetroArch Handled** are codes that RetroArch itself handles by directly scanning/manipulating the emulator/core memory area. # Adding a new cheat code If you have a code that doesn't exist in the cheat database that you want to add manually, perform the following steps: 1. Load the game in question and open the "Cheats" menu from the Quick Menu. 2. Select either "Add New Code to Top" or "Add New Code to Bottom". 3. Navigate to the newly added cheat code line and press enter to bring up the cheat code details. 4. Select the "Code" menu item and press enter. A popup text-entry screen will appear. Type in your new code and press enter. 5. Optionally perform the same steps for the "Description" menu item to edit the description. 6. Ensure the "Enabled" field is set to on. 7. Navigate back one level to the cheats menu and select "Apply Changes". # RetroArch new cheat code searching RetroArch now has the ability to search for and create new cheat codes. The following is an overview for finding new cheats: 1. Start game 2. Go to Quick Menu -> Cheats -> Start or Continue Cheat Search 3. Use left/right on "Start or Restart Cheat Search" to select a bit-size appropriate to the console you are using and the value your are searching. - For example, if you are playing Castlevania:SOTN on the PS1 and you want to search for the health value, then that's a value that can be greater than 255 (0xFF), but it's unlikely that the game developers anticipated a value larger than 65535 (0xFFFF) so set the search to 16-bit. - An alternate example - if you are playing Space Invaders on Atari 2600 and you want to search for the number of lives, then that's a value that could possibly be stored in just 2-bits of data (max number of lives = 3) and since the Atari 2600 only has a very small memory space, it's entirely possible that the memory location for the number of lives is only partially stored in a single byte while the rest of that same byte may store other important data that should not be touched. Set the size to 2-bit. 4. Select "Start or Restart Cheat Search" once you have selected the bit size 5. Go back to the game and lose a life 6. Go back to the quick menu and select "Search Memory For Values ... Less Than Before" because when you started the search you had one more life than you do now. You could also try "Search Memory For Values ... Equals To Before-1". The number of matches should go down. 7. If the number of matches is still too great to peruse, then perform actions 5 and 6 repeatedly until the number of matches is something you feel comfortable trying (e.g. 10). If you run out of lives, just reset the game or restore a save state. Then your lives will likely be greater than the last time you checked, so select "Search Memory For Values ... Greater Than Before" 8. Once you have a manageable list, select "Add the ## Matches to Your List" 9. Go back one menu to see the codes that have been added. Try turning just one on at a time to see if it has the desired effect. If not, turn it off and try the next one. One of them should be the location in memory that stores your number of lives and enabling the cheat in its default state will result in that memory location being overwritten by the cheat value continuously and voila infinite lives. 10. Alternately, you can "Search Memory For Values ... Equal to ###" if you know the exact number (e.g. the number of hit points you have in an RPG). # RetroArch cheat code spanning/sliding/repeating You can also use the "Number of Iterations", "Value Increase Each Iteration", and "Address Increase Each Iteration" options to create a single code that affects a wide range of memory values. This is useful for things like unlocking all levels, giving yourself 1 of every item, setting all of your RPG stats to 999, etc. Usually when you have found a cheat for a specific item (e.g. your strength attribute in an RPG), similarly themed values are found in the same memory area. For example, if the strength attribute was found at memory address 0x0000AB04 then the dexterity attribute might be at 0x0000AB08, intelligence at 0x0000AB0C, etc. This feature is also useful for experimenting. If you found your strength attribute at memory address 0x0000AB04, then you might increase the number of iterations by 20 to see what changes in the game and if any of those changes are desirable. Note that experimenting like this has a good chance of crashing your game, so have a save state prepared before blindly attempting to write to memory. Settings example: Your game has the following values/memory addresses : - 0x0000AB04 - Strength - 0x0000AB08 - Dexterity - 0x0000AB0C - Constitution - 0x0000AB10 - Intelligence A single code can update all of those values: - Memory Search Size - 32 bit - Memory Address - 0x0000AB04 - Value - 900 (0x00000384) - Number of Iterations - 4 - Value Increase Each Iteration - 5 - Address Increase Each Iteration - 1 The starting address is 0x0000AB04 which will be set to value 900. Then for each of the 4 (Number of Iterations) iterations, it will add 1 of the "Memory Search Size" (1 * 32 bits = 4 bytes) to the address and 5 to the value and then set that as well. The final result will have updated these 4 memory locations to be: - 0x0000AB04 - Strength = 900 - 0x0000AB08 - Dexterity = 905 - 0x0000AB0C - Constitution = 910 - 0x0000AB10 - Intelligence = 915 The "Value Increase Each Iteration" would normally be 0 in the above scenario but was used for illustrative purposes. # RetroArch rumble codes RetroArch also has the ability to make your controller rumble when changes in the emulator/core memory occur. It is based off of the same RetroArch-handled cheat codes described above. For example, after finding the memory location for the number of lives in a game (via the cheat searching interface) you can set it up such that every time the value decreases (lose a life) the controller rumbles. Rumble tested with X360 controller, input driver dinput, controller driver xinput. Available rumble controls: - Rumble when memory value changes - Rumble when memory value does not change - Rumble when memory value decreases - Rumble when memory value increases - Rumble when memory value = value - Rumble when memory value != value - Rumble when memory value < value - Rumble when memory value > value - Rumble when memory value decreases by a specific amount - Rumble when memory value increases by a specific amount ================================================ FILE: docs/guides/cli-intro.md ================================================ # RetroArch CLI RetroArch can be used from its robust graphical interfaces as well as a powerful command-line interface (CLI). Getting familiar with the command-line helps you understand the design principles of RetroArch. Note: please be aware of whether your system uses DOS/Windows style paths with backslashes `\` or Unix-style paths with forward slashes: `/`. Some cores like [ScummVM](https://docs.libretro.com/library/scummvm/) (which also has an inbuilt GUI file browser), do not require any content file name passed as a command line argument. This is determined by the core info files with the line `supports_no_game = "true"`. In this case, after you have loaded the core and if it is not starting directly, select 'Start Core' that will appear inside the main menu. #### On macOS: invoking the RetroArch CLI executable /Applications/RetroArch.app/Contents/MacOS/RetroArch #### Example: loading a ROM and libretro core (Unix-style path) retroarch -L /path/to/libretro/core.so game.rom #### Example: loading a ROM and libretro core with flatpak retroarch -L /path/to/libretro/core.so game.rom flatpak run org.libretro.RetroArch/x86_64/stable -L /home/MYUSERNAME/.var/app/org.libretro.RetroArch/config/retroarch/cores/nestopia_libretro.so Tetris.nes #### Example: loading a ROM and libretro core with Steam steam -applaunch 1118310 -L "/path/to/steamapps/common/RetroArch/cores/nestopia_libretro.so" "/path/to/Tetris.nes" Content filenames require no spaces, as there is an issue with Steam passing through command line arguments containing spaces. ## Verbose logging output To get a better idea on what's going on, use the `--verbose` flag. If you want to report a bug, it is **vital** that this log is included. ## Using a config file By default, RetroArch looks for a config in various places depending on OS: - **Linux/macOS**: `$XDG_CONFIG_HOME/retroarch/retroarch.cfg`, then `~/.config/retroarch/retroarch.cfg`, then `~/.retroarch.cfg`, and finally, as a fallback, `/etc/retroarch.cfg`. - **Windows**: `retroarch.cfg` in same folder as `retroarch.exe`, then `%APPDATA%\retroarch.cfg`. To override this, use `retroarch --config customconfig.cfg`. If you have some special options you want to store in separate config files, you can use `retroarch --config baseconfig.cfg --appendconfig specialconfig.cfg`. Be sure to pass `--menu` as well if you aren't loading content directly from the command-line, or RetroArch will close immediately after launching. See man-page and/or `--help` for detail. ## Other essential CLI flags ### retroarch --help Use the `--help` help flag to display RetroArch's built-in CLI documentation. You'll probably discover some features you didn't think about. ### retroarch --features If you're unsure if a particular feature is compiled in, execute `retroarch --features` ================================================ FILE: docs/guides/controller-autoconfiguration.md ================================================ # Joypad Auto Configuration ## Why is it needed? RetroArch runs on many platforms. Each of these platforms has one or more input systems. These input systems in turn differ widely in the way they enumerate the pad buttons. For this reason, your joypad buttons may be mapped differently depending on if you are using Windows, Mac, or Linux. Traditional emulators allow you map each button of your pad to the original pad of the emulated system. For example, this is how the Snes9x joypad configuration interface looks: ![Snes9x joypad configuration](../image/retroarch/input/snes9x-joyconfig-example.jpg) RetroArch also allows this kind of manual mapping. However, RetroArch tries to go further by detecting your joypad and automatically configuring it so manual configuration becomes obsolete. ## Benefits With RetroArch joypad auto-configuration system, your joypad will be recognized and will work out of the box. This allows: - Use many different joypads and have them attributed to each players like it would work on a real game console. - Unplug the second joypad, and replace it by another one, even if it's of a different brand and model. Having automatically configured joypads makes it a lot easier to navigate the RetroArch Menu with the joypad. This is very convenient when running RetroArch on a game console, where a keyboard and a mouse are not always available. It is also what makes RetroArch suitable to build your own game console using Lakka or a similar OS. ## Installing or updating joypad profiles ![downloading joypad profiles](../image/retroarch/input/update-joypads.jpg) The set of joypad profiles used by RetroArch can be downloaded and updated from the menu. Go to `Main Menu` -> `Online Updater` -> `Update Controller Profiles` to get the latest version of the profile pack. A message will appear at the bottom of the screen showing the download progress and the extraction of the archive. ## Generating a joypad profile If your joypad is not recognized by RetroArch even after updating the profiles, you can generate a profile from the menu. 1. To avoid other controllers from interfering with your mapping when starting RetroArch, follow these steps: Disconnect all joypads by unplugging their cables or disconnecting them from any wireless connections. 2. Connect the controller intended for autoconfiguration. Ensure your system supports the selected connectivity method. If your joypad supports both wired and wireless connections and the initial attempt (e.g., via USB) fails, try the alternative option (e.g., Bluetooth). For example, the Nintendo Switch Pro Controller does not support USB connection on Linux 5.15 and older but does support Bluetooth. 3. For Android, run the [Android](#android) steps first. 4. Use `Settings` -> `Input` -> `RetroPad Binds` -> `Port 1 Controls` -> `Set All Controls`. If automatic mapping fails for any button (e.g., due to lack of driver support), the process will be interrupted. In case of interruption, manually map the remaining buttons, starting from the one that caused the interruption and continuing through the rest of the list. 5. Use `Settings` -> `Input` -> `RetroPad Binds` -> `Port 1 Controls` -> `Save Controller Profile` 6. The new profile file (also known as the autoconfig file) will be saved to your disk: [Controller profile directory]/[Controller driver]/[Device index].cfg. 7. Proceed with the manual configuration step section below. ## How does RetroArch match controllers? When you connect a new controller to RetroArch, the system attempts to automatically configure it by matching it to known profiles. This matching process is crucial for ensuring that your controller works correctly with various games and emulators. The matching algorithm considers several key factors: - **Controller driver (input_driver)**: The software interface used to communicate with the controller. To use a specific driver, RetroArch must be configured accordingly by navigating to **Settings -> Drivers -> Controller**. - **Device Index (input_device)**: The name of the controller as recognized by the system. The **Device Index** can be identified by navigating to **Settings -> Input -> RetroPad Binds -> Port 1 Controls**. - **Vendor ID (input_vendor_id)**: A unique identifier assigned to the controller's manufacturer. - **Product ID (input_product_id)**: A specific identifier for the particular controller model. - **Physical ID (input_phys)**: A locally generated identifier in supported drivers, only valid for one specific controller instance / USB port. ### Matching process RetroArch compares these factors against the files in the autoconfig directorys. It calculates a matching score for each profile, selecting the one with the highest score to configure the controller. The combination of Vendor ID and Product ID is often referred to as "vid:pid" in technical contexts. This automated matching system allows RetroArch to support a vast array of controllers, reducing the need for manual setup in most situations. ### Physical identifier customization Supported controller drivers (currently, this is only Linux/udev) will interrogate further physical details about the controller: USB port and serial number. The value of this attribute can be determined from RetroArch debug logs. A few examples (serial redacted): ``` [DEBUG] [Autoconf] Config files scanned: driver udev, pad name Microsoft Xbox Series S|X Controller (045e/0b12), phys usb-0000:04:00.0-2/input0, affinity 41 [DEBUG] [Autoconf] Config files scanned: driver udev, pad name Sony Interactive Entertainment Wireless Controller (054c/09cc), phys 28:c1:3c:__:__:__, affinity 50 ``` Both identifiers will be queried, but support is not guaranteed. In the example above, one has the USB port, the other has the serial number. To use the physical identifier for matching, duplicate the existing autoconfig file (to avoid overwriting it when pulling an update), and extend it with the `input_phys` attribute. Partial matches are supported. ``` input_phys = "usb-0000:04:00.0-2" ``` It is also worth to change `display_name`, to immediately see if the match went as expected. ## Autoconfig variable policy | Controller driver | input_vendor_id/input_product_id required | input_device usage | input_device name variability policy |-|-|-|-| | android | Yes | input_device[^3] | Use the Bluetooth name since it's primarly used by Android devices. | udev | Yes | input_device[^3] | For optimal configuration, if you are generating Linux raw autoconfig files, it is advisable to reuse the variables for input_device and alternative_input_device. In cases where input_device is used without alternative names, it is recommended to utilize the USB Device Index for a more descriptive identification. | linuxraw | No | input_device (for Device Index over USB), input_device_alt1 (for Device Index over Bluetooth), input_device_alt2 (for Device Index over USB on another Linux kernel)... | Use both Device Index over USB and Bluetooth from different Linux kernels; Their names can differ depending on the Linux version in use. | sdl2 | Yes | input_device[^3] | No (uses [SDL2 Game Controller community database](https://github.com/mdqinc/SDL_GameControllerDB/blob/master/gamecontrollerdb.txt)) ## Alternative variables Managing Controllers with Identical Configurations. Up to nine alternative variables can be used for the following purposes: - **`linuxraw`: Managing Controllers with Identical Configurations**: - **Device Index (input_device)**: You can use `input_device_alt1`, `input_device_alt2`, `input_device_alt3`, up to `input_device_alt9`. For names available on both USB and Bluetooth, input_vendor_id should be utilized; for USB-specific names, use input_vendor_id_alt1, and for Bluetooth-specific names, use input_vendor_id_alt2. - **`android`, `sdl2`, and `udev`: Managing Controllers with Identical Configurations that has different input_vendor_id/input_product_id**: - This applies to controllers like the Sony DualShock v1 and v2 for the `android`, `sdl2`, and `udev` controller drivers. Always use `input_vendor_id` and `input_product_id` for the most recent controller models, as they are more likely still available on the market. RetroArch version 1.19.1 and earlier cannot utilize _alt autoconfig variables, so using `input_vendor_id` for the latest controller ensures connectivity in RetroArch. Use `..._alt*` variables for older controllers. - **Vendor ID (input_vendor_id)**: Options include `input_vendor_id_alt1`, `input_vendor_id_alt2`, `input_vendor_id_alt3`, up to `input_vendor_id_alt9`. - **Product ID (input_product_id)**: Options include `input_product_id_alt1`, `input_product_id_alt2`, `input_product_id_alt3`, up to `input_product_id_alt9`. ### Similarities in input variable generation between linuxraw and udev. It's useful to know that the `linuxraw` driver generates identical file content as udev with the exception of the `input_driver` variable, and the DPAD inputs, which are handled differently: #### linuxraw The `linuxraw` driver specifies DPAD inputs using axis values, providing precise control over directional inputs. For example: ``` input_up_axis = "-5" input_down_axis = "+5" input_left_axis = "-4" input_right_axis = "+4" ``` - **autoconfig/linuxraw/Nintendo Switch Pro Controller.cfg example:** ``` input_driver = "linuxraw" input_device = "Nintendo Switch Pro Controller" input_b_btn = "0" input_y_btn = "3" input_select_btn = "9" input_start_btn = "10" input_up_axis = "-5" input_down_axis = "+5" input_left_axis = "-4" input_right_axis = "+4" input_a_btn = "1" input_x_btn = "2" input_l_btn = "5" input_r_btn = "6" input_l2_btn = "7" input_r2_btn = "8" input_l3_btn = "12" input_r3_btn = "13" input_l_x_plus_axis = "+0" input_l_x_minus_axis = "-0" input_l_y_plus_axis = "+1" input_l_y_minus_axis = "-1" input_r_x_plus_axis = "+2" input_r_x_minus_axis = "-2" input_r_y_plus_axis = "+3" input_r_y_minus_axis = "-3" ``` #### udev Udev consistently generates the following: ``` input_up_btn = "h0up" input_down_btn = "h0down" input_left_btn = "h0left" input_right_btn = "h0right" ``` - **autoconfig/udev/Nintendo Switch Pro Controller.cfg example:** ``` input_driver = "udev" input_device = "Nintendo Switch Pro Controller" input_vendor_id = "1406" input_product_id = "8201" input_b_btn = "0" input_y_btn = "3" input_select_btn = "9" input_start_btn = "10" input_up_btn = "h0up" input_down_btn = "h0down" input_left_btn = "h0left" input_right_btn = "h0right" input_a_btn = "1" input_x_btn = "2" input_l_btn = "5" input_r_btn = "6" input_l2_btn = "7" input_r2_btn = "8" input_l3_btn = "12" input_r3_btn = "13" input_l_x_plus_axis = "+0" input_l_x_minus_axis = "-0" input_l_y_plus_axis = "+1" input_l_y_minus_axis = "-1" input_r_x_plus_axis = "+2" input_r_x_minus_axis = "-2" input_r_y_plus_axis = "+3" input_r_y_minus_axis = "-3" ``` ## Before you begin Make sure that you run the latest version of RetroArch, to generate a file name and file content via `Settings` -> `Input` -> `RetroPad Binds` -> `Port 1 Controls` -> `Save Controller Profile` that is up to date with our current policies. ## Modify the Controller Profiles Directory for Non-Root User Accessibility Both the Flatpak and Android versions of RetroArch need adjustments to the Controller Profiles Directory to ensure essential functionality and smooth operation. **Challenges for Android and Flatpak:** - Users are unable to save custom profiles through the path: `Settings -> Input -> RetroPad Binds -> Port 1 Controls -> Save Controller Profile`. - Modification Restrictions: You are not allowed to change existing autoconfig files. Files that are initially disabled have "(default-off)" in their names. Without root access, you cannot modify these files to toggle the input_vendor_id and input_product_id settings. This restriction applies to both the "(default-off)" files and the "original" autoconfig files, which are more widely used and have been set to be enabled by default. These original files must also be commented to make changes. This limitation affects both HID and non-HID files, as well as controllers with multiple autoconfig files, such as the Sony DualSense controller, which includes several Android autoconfig files. ### Android Configuration **Challenge:** Most Android devices are not rooted, and RetroArch's default autoconfig directory requires root access, leading to the following issues: - Restricted File Access: Users can update controller profiles via `Main Menu -> Online Updater -> Update Controller Profiles`, but cannot access these files in `/data/user/0/com.retroarch/autoconfig`. Android's security model prevents non-root users from reading certain files, making it difficult to compare updated profiles with custom-generated ones, thus hindering effective profile management and customization. - Modification Restrictions: Existing autoconfig files cannot be modified when necessary (refer to the base section for more details). **Resolution:** - Create the directory `/storage/emulated/0/RetroArch/autoconfig/android`. - In RetroArch, change the directory path under `Settings` -> `Directory` -> `Controller Profiles` from `/data/user/0/com.retroarch/autoconfig` (root) to `/storage/emulated/0/RetroArch/autoconfig`. - This adjustment allows the autoconfig files to be saved in `/storage/emulated/0/RetroArch/autoconfig/android` when using `Settings` -> `Input` -> `RetroPad Binds` -> `Port 1 Controls` -> `Save Controller Profile`. #### Addressing controller navigation issues on non-touchscreen devices Your controller will use the Controller Profile directory `/data/user/0/com.retroarch/autoconfig` by default in Android. Any autoconfig file that mathces your controller (Vendor ID/Product ID) be used by RetroArch automatically. However, you will not be able to generate a **new** autoconfig file for your controller if a default autoconfig file encounter issues with the following components: * **DPAD**: Essential for navigating menus. * **OK**: Necessary for applying settings, such as navigating to `Settings -> Input -> RetroPad Binds -> Port 1 Controls`, and selecting `Set All Controls` and `Save Controller Profile`. * **Back**: Needed to return to `Main Menu -> Quit` after configuring `Settings -> Directory -> Controller Profiles`, ensuring the settings are saved to retroarch.cfg. Workaround if you have access to another controller: Temporarily connect another controller with a functioning autoconfig "Back" button and adjust the Controller Profiles directory: - `Settings -> Directory -> Controller Profiles`. - `Main Menu -> Quit` -- ensuring the settings are saved to retroarch.cfg. - Disconnect the controller from BlueTooth. While these issues are not problematic for typical Android devices like smartphones and tablets, which offer touchscreen navigation, they become significant on Google TV (an Android-based OS used by Chromecast) where a touchscreen is unavailable. Additionally, Chromecast's voice remote control lacks autoconfiguration and is incompatible with RetroArch navigation. Even controllers with touchpads are ineffective, as the touchpad button does not function (as observed with PS4/PS5 controllers), and the cursor remains invisible due to a known [bug](https://github.com/libretro/RetroArch/issues/16853). **Proposed Solution:** To resolve this issue, follow these steps: - **Create a Custom Configuration File:** - Create the file `retroarch.cfg` in the directory `/storage/emulated/0/Android/com.retroarch/files/retroarch.cfg` with the following line: ``` joypad_autoconfig_dir = /storage/emulated/0/RetroArch/autoconfig/ ``` - **Set Up a Fallback Configuration:** - Identify the Product ID and Vendor ID of your controller: Ensure that the directory /storage/emulated/0/RetroArch/autoconfig/ remains empty, then restart RetroArch. This action will compel RetroArch to enter fallback mode, displaying a message like "[Controller name] ([Vendor ID]/[Product ID]) not configured, using fallback". Record the four-digit numbers for both IDs. - Create a file named `fallback.cfg` in the directory `/storage/emulated/0/RetroArch/autoconfig/android/` with the following configuration settings (don't forget to replace `input_vendor_id = "[Vendor ID]"` and `input_product_id = "[Product ID]"` with the values of your controller: ``` input_driver = "android" input_device = "Fallback device" input_vendor_id = "[Vendor ID]" input_product_id = "[Product ID]" input_b_btn = "96" input_y_btn = "97" input_select_btn = "98" input_start_btn = "99" input_up_btn = "h0up" input_down_btn = "h0down" input_left_btn = "h0left" input_right_btn = "h0right" input_a_btn = "100" input_x_btn = "101" input_l_btn = "102" input_r_btn = "103" input_l2_btn = "104" input_r2_btn = "105" input_l3_btn = "106" input_r3_btn = "107" input_l_x_plus_axis = "+0" input_l_x_minus_axis = "-0" input_l_y_plus_axis = "+1" input_l_y_minus_axis = "-1" input_r_x_plus_axis = "+2" input_r_x_minus_axis = "-2" input_r_y_plus_axis = "+3" input_r_y_minus_axis = "-3" ``` - **Launch RetroArch:** - Start the RetroArch application. - **Button Testing:** - Test the controller buttons to identify which ones correspond to the "OK" and "Back" functions. This will allow you to navigate and temporarily reconfigure RetroArch. By applying this solution, you allow your controller to configure RetroArch, enabling navigation to Settings -> Input -> RetroPad Binds -> Port 1 Controls and the selection of Set All Controls and Save Controller Profile. This setup also permits the saving of autoconfig files in the directory /storage/emulated/0/RetroArch/autoconfig/android. ### Flatpak Configuration **Challenge:** The default autoconfig directory in Flatpak RetroArch also requires root access, which prevents users from: - Downloading and extracting profiles through `Main Menu` -> `Online Updater` -> `Update Controller Profiles`. - Saving custom profiles via `Settings -> Input -> RetroPad Binds -> Port 1 Controls -> Save Controller Profile`. - Modification Restrictions: Facing similar issues as Android users if the GNU/Linux user lacks root access, as existing autoconfig files cannot be modified when necessary (refer to the base section for more details). #### Resolution To address this issue, configure RetroArch as follows: 1. Enable Hidden File Visibility * Navigate to `Main Menu -> Load Content -> File Browser` * Enable the option `Show Hidden Files and Directories` 2. Modify Controller Profiles Directory * Go to `Settings -> Directory -> Controller Profiles` * Change the directory from the default `/app/share/libretro/autoconfig` to `/home/youruser/.var/app/org.libretro.RetroArch/config/retroarch/autoconfig`. Note: The actual path of the default directory is: /var/lib/flatpak/app/org.libretro.RetroArch/current/active/files/share/libretro/autoconfig/ By implementing these changes, you'll be able to create and save custom controller profiles without requiring root privileges. ### Additional manual configuration steps #### Add hotkey(s) When using RetroArch, not all controller buttons are automatically mapped through the "Set All Controls" option. Some buttons—such as menu toggles, screenshot triggers, or other special functions—must be configured separately. Here’s a step-by-step guide to ensure all your controller buttons work as desired. 1. Identify special buttons on your controller - Look for buttons on your physical controller not automatically mapped by Retroarch. - Examples include - *Menu Toggle* (virtually all controllers have them) - Additional special buttons may be found on some controllers. For example, the *Capture* (screenshot) and the "Home" button on Nintendo Switch Pro Controller. 3. Assign hotkeys in Retroarch - Launch Retroarch. - Navigate to: `Settings` → `Input` → `Hotkeys`. - Select the special function you want to assign (e.g., *Menu Toggle*, *Screenshot*). - Press the desired button on your controller to bind it. - Exit Retroarch properly to save the settings: - On most platforms, just closing Retroarch saves the config. - On Android, explicitly quit via `Main Menu` → `Quit` to ensure settings are saved. 4. Transfer hotkey assignments to your controller autoconfig file - Open your main `retroarch.cfg` file. - Find and copy the hotkey assignment lines, for example: ``` input_menu_toggle_btn = "[w]" input_screenshot_btn = "[x]" ``` *(Replace `[w]` and `[x]` with your actual button values.)* - Open your controller’s autoconfig file, typically found at: ``` retroarch/autoconfig/[platform]/[controller-name].cfg ``` - Append the copied hotkey lines to the bottom of the autoconfig file. 5. Add labels. They will be visible in `Settings` → `Input` → `Hotkeys`. - Add variable names. Complement the variables that you just added to the autoconfig file with the corresponding label variables ([variable name]+"_label") at the absolute bottom of the file, for example: ``` input_menu_toggle_btn_label = "[y]" input_screenshot_btn_label = "[z]" ``` *(Replace `[y]` and `[z]` with the appropriate label values described below.)* - Add the corresponding variable label values. Refer to the manufacturer’s official labeling for each button, but avoid using all capital letters unless the name is an abbreviation. Use standard capitalization with an initial capital letter to improve readability. Also, do not add the word “button” if it is already part of the official name. For instance, Nintendo refers to the “HOME button” on the Switch Pro Controller, but you should label it simply as “Home.” Similarly, the menu toggle label for Sony PlayStation controllers is “PS.” This approach balances clarity and respect for official naming. 6. Save the autoconfig file. 7. Restart RetroArch and navigate to `Settings` → `Input` → `Hotkeys` to confirm that they look as intended. ### Analog L2/R2 remapping RetroArch has a bug([ref1](https://github.com/libretro/RetroArch/issues/6920), [ref2](https://github.com/libretro/RetroArch/issues/16767)) that causes analog L2/R2 triggers to be incorrectly mapped as digital buttons instead of analog axes when configuring controls through the UI. This affects pressure-sensitive triggers on controllers like PlayStation 2 and later, making some games unplayable due to the lack of analog input. SDL2 is an exception to this issue: SDL2 treats triggers like L2 and R2 as axes, even if they are digital buttons, to keep a consistent interface across controllers. For example, the Nintendo Switch Pro Controller’s triggers are digital but SDL2 maps them as axes, with values jumping from 0 to max instantly. In the SDL2 Nintendo Switch Pro Controller.cfg file, this is reflected by lines like: ``` input_l2_axis = "+4" input_r2_axis = "+5" input_l2_axis_label = "ZL" input_r2_axis_label = "ZR" ``` To address this bug in RetroArch on other controllers or drivers, you need to manually edit the RetroArch config file to set the correct analog axis mappings for L2 and R2. Here's how to find the proper axis values: * Install and run jstest avalible for GNU/Linux (`sudo apt-get install joystick` for Debian-like distros), and Windows. - In GNU/Linux: `jstest /dev/input/js0` - In GNU/Linux virtual machines using QEMU, js0 is designated for the mouse, so you need to use js1 by running the command: `jstest /dev/input/js1` * Slowly press L2 and R2 to identify which axis numbers change * Note the axis numbers that correspond to L2 and R2 * In the autoconfig file, set: ``` input_l2_axis = "+X" (where X is the L2 axis number) input_r2_axis = "+Y" (where Y is the R2 axis number) input_l2_axis_label = "L2 Trigger" input_r2_axis_label = "R2 Trigger" ``` For [example](https://github.com/libretro/retroarch-joypad-autoconfig/pull/1135), if L2 is axis 2 and R2 is axis 5, you would: Replace: ``` input_l2_btn = "6" input_r2_btn = "7" input_l2_btn_label = "L2" input_r2_btn_label = "R2" ``` With ``` input_l2_axis = "+2" input_r2_axis = "+5" input_l2_axis_label = "L2 Trigger" input_r2_axis_label = "R2 Trigger" ``` Note: These variable values are examples and should not be directly copied to your configuration file. When modifying your autoconfig file for analog triggers, it's crucial to pay attention to both variable names and values. The corresponding label variable names must also be consistent to ensure the configuration works correctly. A common oversight is focusing solely on the values while neglecting to update the variable names themselves. The `_axis` suffix is essential for ensuring proper analog functionality. Simply changing values without updating the suffix from `_btn` to `_axis` will not achieve the desired result. #### Common Pitfall Users often unintentionally incorporate analog variable values without properly adjusting the existing variable names to reflect their analog nature. This oversight frequently results in configuration problems within the system. By carefully updating both the variable names and values, you can ensure that your analog triggers are correctly configured for optimal performance. ### Inspect the file Without modifying anything in the original file, open it in the file in a text editor and 1. Make sure that you have mapped all buttons, and that none of them have duplicated values. 2. Each button should have a variable that ends with `_btn`, or `_axis`, not both. So for example, if you find both `input_a_axis`, and `input_a_btn`, it's incorrect. This may happen if your OS does not support the controller. Before giving up and saving the controller again, you can attempt to re-map any missing buttons. However, please refrain from manually modifying the variables unless it's absolutely necessary due to bugs in RetroArch. If you plan to submit your profile to our joypad profile repository, we depend on automated data for debugging the autoconfig files. ### Try the controller 1. If the controller support Bluetooth, make sure that that there's no Bluetooth latency. 2. Make sure that your mapping is perfect by testing every button in the menu. 3. **Important: Remove previously set manual bindings**: Manual bindings take precedence over autoconfig files. So it's important to remove any manual bindings you may have set previously, as they take priority over autoconfig files. If you've used the Save Controller Profile command, you should reset these bindings. To do this, navigate to Settings -> Input -> RetroPad Binds -> Port 1 Controls -> Reset to Default Controls. Not resetting can cause issues with core responses, such as those from Remote RetroPad and console emulators, particularly if your manual bindings don't match the current controller driver's bindings. A typical problem arises when you create manual bindings, generate an autoconfig file, test them in Remote RetroPad, switch the controller driver to try a different autoconfig file, but forget to Reset to Default Controls first. 4. To verify all controller mappings: `Main Menu` -> `Load Core` -> `Start Remote RetroPad`. Press each button once; icons change white to light green permanently if they are mapped correctly. If icons remain white, try to remap them. Ensure no white buttons remain. Evaluate analog trigger responsiveness for L2 and R2. As you slowly apply pressure, a black rectangle should appear in the center of each button and gradually fade as the pressure increases. Ensure you press the triggers slowly to observe the visual feedback accurately. For Android smartphones and other devices with small displays, hold the screen closer to your eyes. This will help you see the subtle rectangle indicator, which can be difficult to spot at normal viewing distances on compact screens. 5. Try a game in a core that uses all mappings on your controller. After you have loaded the game it's possible that you have to change the native controller to your controller in `Quick Menu` -> `Settings` -> `Input` -> `RetroPad Binds` -> `Port 1 Controls` -> `Device Index` -- for example if you want to use both thumbsticks you have to change `PS1` to `DualShock` in PlayStation cores. If it's difficult for you to find a game that uses all buttons, you can set `Settings` -> `Input` -> `Hotkeys` (for example Save state, Load state, Fastforward, and Rewind) for unused buttons, so you can evaluate all mappings. 6. Use `Settings` -> `Inputs` -> `Port 1 Controls` -> `Reset to Default Controls` to clear manual bindings and rely on the new profile. 7. Unplug your joypad an re-plug it. See if it is auto configured. If you are happy with your profile, you can submit it to RetroArch so that other users benefit: 1. Edit the autoconfig file for your joypad manually to include the input descriptors (please see the [Input descriptors](#input-descriptors) section below) 2. [Submit your profile to our joypad profile repository](https://github.com/libretro/retroarch-joypad-autoconfig) by filing a pull request (PR). - To help us track potential bugs if the autconfig does not work as expected in all RetroArch releases (Flatpak package via Flathub, AppImage via retroarch.com, etc) and their gamepad driver (sdl2, udev, etc), please include a bullet point at the beginning of your PR Comment when submitting a PR. This bullet should specify the RetroArch version you used to generate the autoconfig. Additionally, please add further bullet points to outline what has been added. For example: `* Generated the autoconfig file[s] with RetroArch Flathub's release version x.xx.x` ### Default-off configs When developing controller configurations, it's essential to anticipate and mitigate potential conflicts. These issues often arise in the following situations: 1. When multiple autoconfig files exist for a single device, causing confusion in the system. This primarily occurs with controllers that require different configurations based on kernel versions. For example, the Nintendo Switch Pro Controller on Linux, where older kernels necessitate a different button mapping compared to newer kernels. 2. With poorly constructed unlicensed controllers. Even a single mismatched button can break compatibility, necessitating custom configuration. Here's how to set up a default-off configuration: 1. Append "(default-off)" to the configuration filename. 2. Comment out the `input_device`, `input_vendor_id` and `input_product_id` lines in the config file. 3. Do not add "(default-off)" to the values of the input_device_display_name and input_driver variables in the config file. The default-off status is already indicated by the filename, so these variables should remain unmodified for clarity. This approach allows users to manually enable the configuration when needed, preventing automatic application that could interfere with common devices, and helps ensure a smoother experience for users while still providing the necessary configuration options for those who require them. ### Device Index scheme for autoconfig files In RetroArch, the management of controller configurations is essential for ensuring proper functionality across various systems. This guide outlines how the Device Index are generated. #### Understanding the Device Index RetroArch identifies physical controllers through a system called the Device Index. You can locate this identifier by navigating to: **Settings > Input > RetroPad Binds > Port 1 Binds > Device Index** The Device Index plays a crucial role when saving a controller profile. To save a profile, follow this path: **Settings > Input > RetroPad Binds > Port 1 Controls > Save Controller Profile** ### Dual function of the Device Index When you save a controller profile, the Device Index serves two important purposes: 1. **Configuration File Naming**: It becomes an integral part of the configuration file's name. For example, if the Device Index is "Foo", the configuration file might be named "udev/Foo.cfg". 2. **Input Device Identification**: Within the configuration file itself, the Device Index is used as the value for the `input_device` variable. Following our example, you would see a line like this in the file: `input_device = "Foo"` This dual functionality ensures that RetroArch can correctly identify and apply the appropriate settings for each unique controller. Importantly, this name remains consistent across various controller drivers, such as udev, sdl2, and linuxraw, as specified in **Settings > Drivers > Controller**. ### sdl2 notes SDL2 uses the [SDL2 Game controller community database](https://github.com/mdqinc/SDL_GameControllerDB/blob/master/gamecontrollerdb.txt). You can check it using [SDL2 Gamepad Mapper](https://gitlab.com/ryochan7/sdl2-gamepad-mapper/-/releases). #### Appimage issue Currently, the SDL2 controller driver utilizes UDEV rather than SDL2 in the RetroArch Appimage package. Therfore, use the Flatpak package in order to upload SDL2 autoconfig files. ### linuxraw, and udev naming schemes (depends on multiple Device Indexes) The naming conventions for the controllers may vary between USB and Bluetooth connections depending on the Linux kernel version in use. #### Example of controller with HID and non-HID autoconfigs: Nintendo Switch Pro Controller In Linux kernel versions 5.15.0, 5.19, and 6.2.0, devices connected via USB and Bluetooth are identified as "Nintendo Switch Pro Controller." However, in kernel version 6.8.0, the device is recognized with the USB name "Nintendo Co., Ltd. Pro Controller" and the Bluetooth name "Pro Controller." Consequently, to account for all possible device index names, it is essential to generate autoconfiguration files using various Linux kernel versions to capture all naming variations. | Linux Kernel Version | HID Support | USB Supported | Device Index in RetroArch (USB) | Bluetooth Supported[^2] | Device Index in RetroArch (Bluetooth) | Autoconfig structure | |-|-|-|-|-|-|-| | 5.15 | No | No[^1] | Nintendo Switch Pro Controller | Yes | Nintendo Switch Pro Controller | Generate `Nintendo Switch Pro Controller (default-off).cfg` | | 5.19 | Yes | Yes | Nintendo Switch Pro Controller | Yes | Nintendo Switch Pro Controller | udev/linuxraw: Generate `Nintendo Switch Pro Controller.cfg` | | 6.2.0 | Yes | Yes | Nintendo Switch Pro Controller | Yes | Nintendo Switch Pro Controller | | | 6.8.0 | Yes | Yes | Nintendo Co., Ltd. Pro Controller | Yes | Pro Controller | For linuxraw: Manually add `input_device_alt1 = "Nintendo Co., Ltd. Pro Controller"` and `input_device_alt2 = "Pro Controller"` | In the above list, the following entries under **Autoconfigs file names to generate** are identified and required for the controller to be identified by linuxraw: ##### udev autoconfigs udev primarily uses input_vendor_id and input_product_id, eliminating the need to create multiple files as required by linuxraw. However, an additional non-HID autoconfiguration is necessary in this example, because the bindings differ from those used in the HID autoconfiguration. This is important to ensure that the correct button mappings are applied for devices that do not conform to the HID standard, as they have different layouts that require distinct configurations. - **Nintendo Switch Pro Controller (non-HID) (default-off).cfg**: ``` input_driver = "udev" #input_device = "Nintendo Switch Pro Controller" input_device_display_name = "Nintendo Switch Pro Controller (non-HID)" #input_vendor_id = "1406" #input_product_id = "8201" ``` Note: `(non-HID) (default-off)` is added to the filename to distinguish it from the autoconfig with HID support and to make clear that it is disabled by default. Also, the `input_device`, `input_vendor_id` and `input_product_id` variables are commented out to disable this auto-configuration, preventing file name duplication and conflicts with the HID version: Nintendo Switch Pro Controller.cfg - **Nintendo Switch Pro Controller.cfg**: ``` input_driver = "udev" input_device = "Nintendo Switch Pro Controller" input_vendor_id = "1406" input_product_id = "8201" input_device_alt1 = "Nintendo Co., Ltd. Pro Controller" input_device_alt2 = "Pro Controller" ``` ##### linuxraw autoconfigs Since linuxraw relies solely on input_device, all file names must be included: - **Nintendo Switch Pro Controller (non-HID) (default-off).cfg**: ``` input_driver = "linuxraw" #input_device = "Nintendo Switch Pro Controller" input_device_display_name = "Nintendo Switch Pro Controller (non-HID)" ``` Note: `(non-HID) (default-off)` is added to the filename to distinguish it from the autoconfig with HID support and to make clear that it is disabled by default. Also, the `input_device` variable is commented out to disable this auto-configuration, preventing file name duplication and conflicts with the HID version: Nintendo Switch Pro Controller.cfg - **Nintendo Switch Pro Controller.cfg**: ``` input_driver = "linuxraw" input_device = "Nintendo Switch Pro Controller" input_device_alt1 = "Nintendo Co., Ltd. Pro Controller" input_device_alt2 = "Pro Controller" ``` #### Example of multiple input_product_id variables: DualShock 4 v1, and DualShock 4 v2 **DualShock 4 v2:** | Controller Version | Linux Kernel Version | HID Support | USB Supported | Device Index in RetroArch (USB) | Bluetooth Supported | Device Index in RetroArch (Bluetooth) | Autoconfig Structure | |--------------------|---------------------|-------------|---------------|---------------------------------|---------------------|---------------------------------------|----------------------| | 5.15 | Yes | Yes | Sony Interactive Entertainment Wireless Controller | Yes | Wireless Controller | udev/linuxraw: Generate `Sony DualShock 4 Controller.cfg` (see "Note" below). udev/linuxraw: Manually add DualShock 4 v1 values to input_device_alt1, input_device_display_name_alt1. linuxraw: Manually add: input_vendor_id_alt1, input_product_id_alt1 | | 5.19 | Yes | Yes | Sony Interactive Entertainment Wireless Controller | Yes | Wireless Controller | | | 6.2.0 | Yes | Yes | Sony Interactive Entertainment Wireless Controller | Yes | Wireless Controller | | | 6.8.0 | Yes | Yes | Sony Interactive Entertainment Wireless Controller | Yes | Wireless Controller | | Note: DualShock 4 v1 is known as "Sony Computer Entertainment Wireless Controller" in Linux. However, this controller is not sold any more so extensive evaluation is not possible. However, the configuration is identical for both controllers. ##### udev autoconfigs - **Sony DualShock 4 Controller.cfg**: ``` input_device = "Sony Interactive Entertainment Wireless Controller" input_device_display_name = "Sony Interactive Entertainment Wireless Controller (DualShock 4 v2)" input_driver = "udev" input_vendor_id = "1356" input_product_id = "2508" input_device_alt1 = "Sony Computer Entertainment Wireless Controller" input_device_display_name_alt1 = "Sony Computer Entertainment Wireless (DualShock 4 v1)" input_vendor_id_alt1 = "1356" input_product_id_alt1 = "1476" ``` ##### linuxraw autoconfigs - **Sony DualShock 4 Controller.cfg**: ``` input_driver = "linuxraw" input_device = "Sony Interactive Entertainment Wireless Controller" input_device_display_name = "Sony Interactive Entertainment Wireless Controller (DualShock 4 v2)" input_device_alt1 = "Wireless Controller" input_device_display_name_alt1 = "Wireless Controller (DualShock 4 v2)" input_device_alt2 = "Sony Computer Entertainment Wireless Controller" input_device_display_name_alt2 = "Sony Computer Entertainment Wireless (DualShock 4 v1)" ``` #### Example: Sony DualSense | Linux Kernel Version | HID Support | USB Supported | Device Index in RetroArch (USB) | Bluetooth Supportede[^2] | Device Index in RetroArch (Bluetooth) | Autoconfig structure | |-|-|-|-|-|-|-| | 5.15 | Yes | Yes | Sony Interactive Entertainment DualSense Wireless Controller | Yes | DualSense Wireless Controller | udev/linuxraw: Generate `Sony Interactive Entertainment DualSense Wireless Controller.cfg`. linuxraw: Manually add `input_device_alt1 = "DualSense Wireless Controller"` | | 5.19 | Yes | Yes | Sony Interactive Entertainment DualSense Wireless Controller | Yes | DualSense Wireless Controller | | | 6.2.0 | Yes | Yes | Sony Interactive Entertainment DualSense Wireless Controller | Yes | DualSense Wireless Controller | | | 6.8.0 | Yes | Yes | Sony Interactive Entertainment DualSense Wireless Controller | Yes | DualSense Wireless Controller | | It should be noted that all DualSense controller versions (V1–V5, regardless of firmware version) share the same USB PID 0CE6 under VID 054C, unlike the earlier DualShock 4, whose V1 and V2 models use distinct PIDs. In the above list, the following entries under **Autoconfigs file names to generate** are identified and required for the controller to be identified by linuxraw: ##### udev - **Sony Interactive Entertainment DualSense Wireless Controller.cfg**: ``` input_driver = "udev" input_device = "Sony Interactive Entertainment DualSense Wireless Controller" input_vendor_id = "1356" input_product_id = "3302" ``` ##### linuxraw - **Sony Interactive Entertainment DualSense Wireless Controller.cfg**: ``` input_driver = "linuxraw" input_device = "Sony Interactive Entertainment DualSense Wireless Controller" input_device_alt1 = "DualSense Wireless Controller" ``` ## Troubleshooting If your joypad is not configured properly, you should [generate a RetroArch log](/docs/guides/generating-retroarch-logs.md). Your log will show if a profile has been matched for your pad and the path of the corresponding profile. ## Joypad auto-configuration file ### Metadata The first part of the joypad profile is used for matching the profile with the device, as explained above. The **Vendor ID** and **Product ID** are in decimal format. ``` input_driver = "udev" input_device = "Sony Interactive Entertainment DualSense Edge Wireless Controller" input_vendor_id = "1356" input_product_id = "3570" ``` #### Manually finding Vendor ID and Product ID (VID:PID) on GNU/Linux If you need to manually identify the VID:PID for your controller (for example, if RetroArch does not work as expected for you) in GNU/Linux, you can run this script: ``` read -p "Connect your joypad and press ENTER." lsusb | nl -w2 -s': ' read -p "Enter the number of your joypad device (or ENTER to skip): " n if [[ -z "$n" ]]; then echo "No device selected. Only mapping will be re-generated." exit 0 fi line=$(lsusb | sed -n "${n}p") ids=$(echo "$line" | grep -oP 'ID \K[0-9a-fA-F]{4}:[0-9a-fA-F]{4}') vendor_hex=${ids%%:*} product_hex=${ids##*:} input_product_id=$((16#$vendor_hex)) input_vendor_id=$((16#$product_hex)) echo -e "\ninput_vendor_id = \"$input_product_id\"\ninput_product_id = \"$input_vendor_id\"\n" ######################################## # List all autoconfig files for the selected USB controller search_autoconfig() { local retroarch_dir="$1" if [ ! -f "$retroarch_dir/retroarch.cfg" ]; then echo "Config file not found: $retroarch_dir/retroarch.cfg. Please start RetroArch, and optionally configure Settings -> Directory -> Controller Profiles." return fi # Extract raw joypad_autoconfig_dir from config, strip quotes and spaces local joypad_autoconfig_dir_raw joypad_autoconfig_dir_raw=$(grep "^joypad_autoconfig_dir" "$retroarch_dir/retroarch.cfg" | cut -d= -f2- | tr -d '" ') local joypad_autoconfig_dir # For AppImage, expand ~ to retroarch_dir; for others, expand ~ to $HOME if [[ "$retroarch_dir" == *".AppImage.home/.config/retroarch" ]]; then joypad_autoconfig_dir="${joypad_autoconfig_dir_raw/#\~/$retroarch_dir}" # Remove duplicated ".config/retroarch/" if present twice joypad_autoconfig_dir="${joypad_autoconfig_dir//.config\/retroarch\/.config\/retroarch/.config/retroarch}" else joypad_autoconfig_dir="${joypad_autoconfig_dir_raw/#\~/$HOME}" fi # Fallback to default autoconfig directory if empty if [ -z "$joypad_autoconfig_dir" ]; then joypad_autoconfig_dir="$HOME/.config/retroarch/autoconfig" fi echo "Searching in: $joypad_autoconfig_dir" if [ -d "$joypad_autoconfig_dir" ]; then grep -r "input_product_id = \"$input_vendor_id\"" "$joypad_autoconfig_dir" else echo "Autoconfig directory not found: $joypad_autoconfig_dir" fi echo "" } echo "--- Standard package install ---" search_autoconfig "$HOME/.config/retroarch" echo "--- Flathub (Flatpak) install ---" search_autoconfig "$HOME/.var/app/org.libretro.RetroArch/config/retroarch" echo "--- AppImage install ---" search_autoconfig "$HOME/Downloads/RetroArch-Linux-x86_64/RetroArch-Linux-x86_64.AppImage.home/.config/retroarch" ``` With this you can search for existing autoconfig files matching your controller. This is especially useful to find if your loaded autoconfig has commented variables which happens if there are multiple autoconfigs of the same controller. ### Mapping The second part is the mapping itself, where each button is assigned to a button of the RetroPad (the joypad abstraction of RetroArch). Example ``` input_b_btn = "0" input_y_btn = "2" input_select_btn = "6" input_start_btn = "7" input_up_btn = "h0up" input_down_btn = "h0down" input_left_btn = "h0left" input_right_btn = "h0right" input_a_btn = "1" input_x_btn = "3" input_l_btn = "4" input_r_btn = "5" input_l2_axis = "+2" input_r2_axis = "+5" input_l3_btn = "9" input_r3_btn = "10" input_l_x_plus_axis = "+0" input_l_x_minus_axis = "-0" input_l_y_plus_axis = "+1" input_l_y_minus_axis = "-1" input_r_x_plus_axis = "+3" input_r_x_minus_axis = "-3" input_r_y_plus_axis = "+4" input_r_y_minus_axis = "-4" input_menu_toggle_btn = "8" ``` Note: These variable values are examples and should not be directly copied to your configuration file. #### Input types ##### Buttons (digital inputs) * These are defined by variable names ending with `_btn` (e.g., `input_a_btn`, `input_start_btn`). * The current RetroArch configurations have button values that ranges from `0` to `203`. However, if RetroArch does not limit the values to `203`, underlying controller hardware could offer an even wider range. * RetroArch interprets these IDs (usually 1 for pressed, 0 for not pressed) to determine the button state. ###### D-Pad directions (special digital inputs) * D-pad directions use variable values beginning with `h0` (e.g., `input_up_btn = "h0up"`), for certain controller drivers (e.g udev, and android, but not sdl2). * Four `h0` variables exist (`h0up`, `h0down`, `h0left`, `h0right`) for each direction on the D-pad. * Note: The value `h1` is used by a single controller (Nintendo_Wii_Remote_Classic_Controller.cfg). ##### Axis (analog input) * Axis definitions use `+` and `-` to indicate positive or negative direction (e.g., full press vs. no press). * The current RetroArch configurations have axis values that ranges from `0` to `10`. However, if RetroArch does not limit the values to `10`, underlying controller hardware could offer an even wider range. ###### Mapping variables with analog L2/R2 triggers ``` input_l2_axis = "+[x]" input_r2_axis = "+[y]" ``` Note: These variable values are examples and should not be directly copied to your configuration file, they will not work. #### Controller elements ##### Axes (analog inputs) * They represent analog inputs from the controller, like joystick position (e.g., left joystick X-axis, right joystick Y-axis) or trigger pressure (e.g., L2 trigger, R2 trigger). * Variable names (for both mappings and labels) includes `_axis` define these (e.g., `input_l_x_plus_axis_label`, `input_r2_axis`). | Console | Controller | Release Date | Analog Thumb Sticks | L2/R2 Trigger | |------------------|----------------------------------|----------------|---------------------|--------------| | PlayStation 1 | Sony Dual Analog Controller | April 1997 | Yes | No | | PlayStation 1 | Sony DualShock | November 1997 | Yes | No | | PlayStation 2 | DualShock 2 | 2000 | Yes | Yes | | PlayStation 3 | Sixaxis | 2006 | Yes | Yes | | PlayStation 3 | DualShock 3 | 2008 | Yes | Yes | | PlayStation 4 | DualShock 4 | 2013 | Yes | Yes | | PlayStation 5 | DualSense | 2020 | Yes | Yes | ###### Shoulder buttons with analog variables Give each button the same label as described by the manufacturer. Additionally: - For analog shoulder buttons, use the manufacturer’s label **and** append the word **" Trigger"** at the end. - For example: `input_l2_axis_label = "L2 Trigger"` ###### Analog sticks The term "Analog" is included in the variable values for the analog inputs to clearly indicate that these inputs are analog in nature. Labels for analog thumb sticks: ``` input_l_x_plus_axis_label = "Left Analog X+ (Right)" input_l_x_minus_axis_label = "Left Analog X- (Left)" input_l_y_plus_axis_label = "Left Analog Y+ (Down)" input_l_y_minus_axis_label = "Left Analog Y- (Up)" input_r_x_plus_axis_label = "Right Analog X+ (Right)" input_r_x_minus_axis_label = "Right Analog X- (Left)" input_r_y_plus_axis_label = "Right Analog Y+ (Down)" input_r_y_minus_axis_label = "Right Analog Y- (Up)" ``` #### Input descriptors The third part are *input descriptors* used by RetroArch to display the labels of the buttons as they are written on your joypad. RetroArch does not automatically generate button labels; therefore, you need to manually add them to your autoconfig file. Generic input descriptors: ``` input_b_btn_label = "A" input_y_btn_label = "X" input_select_btn_label = "Back" input_start_btn_label = "Start" input_up_btn_label = "D-Pad Up" input_down_btn_label = "D-Pad Down" input_left_btn_label = "D-Pad Left" input_right_btn_label = "D-Pad Right" input_a_btn_label = "B" input_x_btn_label = "Y" input_l_btn_label = "LB" input_r_btn_label = "RB" input_l2_axis_label = "LT" input_r2_axis_label = "RT" input_l3_btn_label = "Left Thumb" input_r3_btn_label = "Right Thumb" input_l_x_plus_axis_label = "Left Analog X+ (Right)" input_l_x_minus_axis_label = "Left Analog X- (Left)" input_l_y_plus_axis_label = "Left Analog Y+ (Down)" input_l_y_minus_axis_label = "Left Analog Y- (Up)" input_r_x_plus_axis_label = "Right Analog X+ (Right)" input_r_x_minus_axis_label = "Right Analog X- (Left)" input_r_y_plus_axis_label = "Right Analog Y+ (Down)" input_r_y_minus_axis_label = "Right Analog Y- (Up)" input_menu_toggle_btn_label = "Guide" ``` #### Example: Controllers for Sony PlayStation 2 and later Labels for PlayStation controllers starting from PS2. Note that analog L2/R2 triggers (`input_l2_axis_label = "L2 Trigger"`, and `input_r2_axis_label = "R2 Trigger"`) are featured: ``` input_b_btn_label = "Cross" input_y_btn_label = "Square" input_select_btn_label = "Create" input_start_btn_label = "Options" input_up_btn_label = "D-Pad Up" input_down_btn_label = "D-Pad Down" input_left_btn_label = "D-Pad Left" input_right_btn_label = "D-Pad Right" input_a_btn_label = "Circle" input_x_btn_label = "Triangle" input_l_btn_label = "L1" input_r_btn_label = "R1" input_l2_axis_label = "L2 Trigger" input_r2_axis_label = "R2 Trigger" input_l3_btn_label = "L3" input_r3_btn_label = "R3" input_l_x_plus_axis_label = "Left Analog X+ (Right)" input_l_x_minus_axis_label = "Left Analog X- (Left)" input_l_y_plus_axis_label = "Left Analog Y+ (Down)" input_l_y_minus_axis_label = "Left Analog Y- (Up)" input_r_x_plus_axis_label = "Right Analog X+ (Right)" input_r_x_minus_axis_label = "Right Analog X- (Left)" input_r_y_plus_axis_label = "Right Analog Y+ (Down)" input_r_y_minus_axis_label = "Right Analog Y- (Up)" input_menu_toggle_btn_label = "PS" ``` ### Avoid blank lines When RetroArch generates autoconfig files through Settings -> Input -> RetroPad Binds -> Port 1 Controls -> Save Controller Profile, it does not include empty line breaks. If you manually insert an empty line before the label variables and later modify any variable, RetroArch will remove the blank line upon saving again. While blank lines are harmless, they do not adhere to a strict standard. ### Example of a correctly formatted autoconfig file autoconfig/udev/DualSense Wireless Controller.cfg: ``` input_driver = "udev" input_device = "Sony Interactive Entertainment DualSense Wireless Controller" input_device_display_name = "Sony DualSense (BlueTooth)" input_b_btn = "0" input_y_btn = "3" input_select_btn = "8" input_start_btn = "9" input_up_btn = "h0up" input_down_btn = "h0down" input_left_btn = "h0left" input_right_btn = "h0right" input_a_btn = "1" input_x_btn = "2" input_l_btn = "4" input_r_btn = "5" input_l2_axis = "+2" input_r2_axis = "+5" input_l3_btn = "11" input_r3_btn = "12" input_l_x_plus_axis = "+0" input_l_x_minus_axis = "-0" input_l_y_plus_axis = "+1" input_l_y_minus_axis = "-1" input_r_x_plus_axis = "+3" input_r_x_minus_axis = "-3" input_r_y_plus_axis = "+4" input_r_y_minus_axis = "-4" input_menu_toggle_btn = "5" input_b_btn_label = "Cross" input_y_btn_label = "Square" input_select_btn_label = "Create" input_start_btn_label = "Options" input_up_btn_label = "D-Pad Up" input_down_btn_label = "D-Pad Down" input_left_btn_label = "D-Pad Left" input_right_btn_label = "D-Pad Right" input_a_btn_label = "Circle" input_x_btn_label = "Triangle" input_l_btn_label = "L1" input_r_btn_label = "R1" input_l2_axis_label = "L2 Trigger" input_r2_axis_label = "R2 Trigger" input_l3_btn_label = "L3" input_r3_btn_label = "R3" input_l_x_plus_axis_label = "Left Analog X+ (Right)" input_l_x_minus_axis_label = "Left Analog X- (Left)" input_l_y_plus_axis_label = "Left Analog Y+ (Down)" input_l_y_minus_axis_label = "Left Analog Y- (Up)" input_r_x_plus_axis_label = "Right Analog X+ (Right)" input_r_x_minus_axis_label = "Right Analog X- (Left)" input_r_y_plus_axis_label = "Right Analog Y+ (Down)" input_r_y_minus_axis_label = "Right Analog Y- (Up)" input_menu_toggle_btn_label = "PS" ``` # Footnotes [^1]: The controller is listed as "Nintendo Switch Pro Controller" under RetroPad Binds -> Port 1 Controls -> Device Index, but button binding is not possible. [^2]: Ensure that the bluez package is functioning correctly, as detailed in this [bug](https://github.com/bluez/bluez/issues/673). Also, if you're experiencing unreliable Bluetooth connections with virtual machines, which can impact all controllers, consider booting the distributions in live mode directly from the BIOS. [^3]: If there is a misconfiguration of the Vendor ID and Product ID, the system defaults to using the Device Index. Relevant code references include input_autoconfigure_get_config_file_affinity in task_autodetect.c, and input_autoconfigure_connect in android_input.c, sdl_joypad.c, and udev_joypad.c. If you've already created Linuxraw autoconfig names that need alternative input_device variables (such as input_device_alt1, input_device_alt2, etc.), please use them for udev as well since they are using identical Device Indexes. If you haven't, using input_vendor_id/input_product_id will suffice. ================================================ FILE: docs/guides/core-list.md ================================================ | Core | System/Machine | Notes | | :--- | :--- | :--- | | [2048](https://docs.libretro.com/library/2048/) | Game | A port of the popular puzzle game 2048 to libretro | | 3D Engine | - | This is a test core; it demonstrates how to create a hardware-rendered core in a libretro context | | [4DO](https://docs.libretro.com/library/opera/) | 3DO | | | a5200 | Atari 5200 | | | Anarch | Game | A port of Anarch, 90s-style Doom clone shooter game | | [Ardens](../library/ardens.md) | Arduboy | A simulator for the Arduboy FX | | Arduous | Arduboy | A emulator for Arduboy, a handheld game console with open source software, based on the Arduino hardware platform | | [Atari800](https://docs.libretro.com/library/atari800/) | Atari 5200 | | | [b2](../library/b2.md) | Acorn BBC Micro | | | [Beetle bsnes](../library/beetle_bsnes.md) | Nintendo SNES/SFC | | | [Beetle Cygne](https://docs.libretro.com/library/beetle_cygne/) | Bandai WonderSwan/Color | | | [Beetle GBA](../library/beetle_gba.md) | Game Boy Advance | | | [Beetle Lynx](../library/beetle_lynx.md) | Atari Lynx | | | Beetle NeoPop | Neo Geo Pocket/Color | | | Beetle PC-FX | NEC PC-FX | | | Beetle PCE | NEC PC Engine/SuperGrafx/CD | | | Beetle PCE FAST | NEC PC Engine/CD | | | Beetle PSX | Sony PlayStation | | | Beetle PSX HW | Sony PlayStation | A fork of Mednafen's PSX providing GPU-accelerated renderers for OpenGL and Vulkan | | Beetle Saturn | Sega Saturn | | | Beetle SuperGrafx | NEC PC Engine/SuperGrafx | | | Beetle Supafaust | Nintendo SNES/SFC | | | [Beetle VB](../library/beetle_vb.md) | Nintendo Virtual Boy | | | [BK](../library/bk.md) | Elektronika BK-0010/BK-0011(M)/Terak 8510-a | A port of the PDP11 emulator to libretro. This core emulates the PDP-11/03 platform. | | BlastEm | Sega Genesis (Mega Drive) | | | [blueMSX](../library/bluemsx.md) | MSX/SVI/ColecoVision/SG-1000 | | | [bnes](../library/bnes.md) | Nintendo NES/Famicom | | | boom 3 | Game engine | A port of the Doom 3 engine to libretro. There is a separate core for it's expansion pack 'Resurrection of Evil'. | | boom 3 xp | Game engine | (See boom 3 note) | | bsnes | Nintendo SNES/SFC | | | [bsnes 2014 Accuracy](../library/bsnes_accuracy.md) | Nintendo SNES/SFC | | | [bsnes 2014 Balanced](../library/bsnes_balanced.md) | Nintendo SNES/SFC | | | [bsnes 2014 Performance](../library/bsnes_performance.md) | Nintendo SNES/SFC | | | [bsnes C++98 (v085)](../library/bsnes_cplusplus98.md) | Nintendo SNES/SFC | | | bsnes-hd beta | Nintendo SNES/SFC | | | [bsnes-jg](../library/bsnes-jg.md) | Nintendo SNES/SFC | | | [bsnes-mercury Accuracy](../library/bsnes_mercury_accuracy.md) | Nintendo SNES/SFC | | | [bsnes-mercury Balanced](../library/bsnes_mercury_balanced.md) | Nintendo SNES/SFC | | | [bsnes-mercury Performance](../library/bsnes_mercury_performance.md) | Nintendo SNES/SFC | | | Cannonball | Game engine | A port of the Cannonball, enhanced OutRun engine to libretro | | [Caprice32](../library/caprice32.md) | Amstrad CPC | | | CDi 2015 | Philips CDi | | | ChaiLove | Game engine | A free, open-source framework used to make 2D games in ChaiScript | | [Citra](../library/citra.md) | Nintendo 3DS | | | Citra 2018 | Nintendo 3DS | | | [Citra Canary](../library/citra_canary.md) | Nintendo 3DS | Based on Citra development branch | | [ClownMDEmu](../library/clownmdemu.md) | Sega MD/CD | | | Craft | Game | A basic clone of the Minecraft sandbox game | | [CrocoDS](../library/crocods.md) | Amstrad CPC | | | Cruzes | Game | (Further information required) | | Daphne | Arcade | | | [DeSmuME](../library/desmume.md) | Nintendo DS | | | [DeSmuME 2015](../library/desmume_2015.md) | Nintendo DS | | | [DICE](../library/dice.md) | Arcade | Pre-CPU games like Pong | | Dinothawr | Game engine | A push-the-block-in-a-straight-line puzzle game in the spirit of Kickle Cubicle | | DirectXbox | Xbox | | | [Dolphin](../library/dolphin.md) | Nintendo GameCube/Wii | | | [DOSBox](../library/dosbox.md) | DOS | | | DOSBox-core | DOS | Provides some improvements over the DOSBox-SVN trunk, including native MIDI support, cycle-accurate OPL3 (YMF262) emulation, MT-32 emulation and experimental 3dfx Voodoo support | | [DOSBox-Pure](../library/dosbox_pure.md) | DOS | A port of DOSBox with a goal of simplicty and ease of use and gameplay. This core includes a streamlined workflow for launching games directly from ZIP archives with automated mapping of controls to gamepads and a native onscreen keyboard. | | DOSBox-SVN | DOS | This core is based on DOSBox-SVN trunk and allows on-the-fly configuration and different sync methods | | [doukutsu-rs](../library/doukutsu-rs.md) | Game engine | An open-source reimplementation of the Cave Story engine compatible with all official (and some unofficial) releases of Cave Story | | DuckStation | Sony PlayStation | | | Dungeon Crawl Stone Soup | Game | A preliminary port of the Dungeon Crawl Stone Soup strategy game | | EasyRPG | RPG Maker 2000/2003 | | | ECWolf | Game engine | A port of the Wolfenstein 3D engine to libretro | | EighyOne | Sinclair ZX 81 | | | Emux CHIP-8 | CHIP-8 | | | [Emux GB](../library/emux_gb.md) | Game Boy/Color | | | [Emux NES](../library/emux_nes.md) | Nintendo NES/Famicom | | | Emux SMS | Sega Master System | | | EmuSCV | Super Cassette Vision | | | [Ep128emu](../library/ep128emu.md) | Enterprise 64/128 | | | FAKE-08 | Pico-8 | A port of the FAKE-08 open-source reimplementation of the PICO-8 fantasy console to libretro | | FB Alpha | Arcade/Console/various | (See FB Neo note) | | FB Alpha 2012 | Arcade/Console/various | (See FB Neo note) | | FB Alpha 2012 CPS-1 | CPS-1 | | | FB Alpha 2012 CPS-2 | CPS-2 | | | FB Alpha 2012 CPS-3 | CPS-3 | | | FB Alpha 2012 Neo Geo | Neo Geo | | | [FB Neo](../library/fbneo.md) | Arcade/Console/various | Full list of supported systems: https://github.com/finalburnneo/FBNeo/wiki | | [FCEUmm](../library/fceumm.md) | Nintendo NES/Famicom | | | FFmpeg | Media player | A port of FFmpeg library which allows playback of a variety of audio and video formats | | fixGB | Game Boy/Color | | | fixNES | Nintendo NES/Famicom | | | Flycast | Sega Dreamcast/NAOMI | | | Flycast GLES2 | Sega Dreamcast/NAOMI | | | fMSX | MSX/MSX2/MSX2+ | | | FreeChaF | Fairchild ChannelF | | | [FreeIntv](../library/freeintv.md) | Mattel Intellivision | | | FreeJ2ME | J2ME | a port of Java 2 Micro Edition emulator | | Frodo | Commodore C64 | | | FS-UAE | Commodore Amiga | | | Fuse | Sinclair ZX Spectrum | | | [GAM4980](../library/gam4980.md) | BBK 4980/4988/5980 electronic dictionary | | [Gambatte](../library/gambatte.md) | Game Boy/Color | | | Game Music Emu | Music player | A port of Game Music Emu which allows playback of a wide variety of video game music formats | | [Gearboy](../library/gearboy.md) | Game Boy/Color | | | [Gearcoleco](../library/gearcoleco.md) | Coleco ColecoVision | | | [Geargrafx](../library/geargrafx.md) | NEC PC Engine/SuperGrafx | | | [Gearlynx](../library/gearlynx.md) | Atari Lynx | | | [Gearsystem](../library/gearsystem.md) | Sega MS/GG/SG-1000 | | | Genesis Plus GX | Sega MS/GG/MD/CD | | | [Geolith](../library/geolith.md) | SNK Neo Geo AES/MVS | Highly accurate emulator for the Neo Geo AES and MVS Cartridge Systems | | [gpSP](../library/gpsp.md) | Game Boy Advance | | | Gong | Game | A clone of Pong written for libretro | | GW | Handheld Electronic | A simulator of various Game and Watch-style handheld electronic games | | [Handy](../library/handy.md) | Atari Lynx | | | [Hatari](../library/hatari.md) | Atari ST/STE/TT/Falcon | | | HBMAME | Arcade/Console/various | HBMAME (HomeBrew MAME) is a derivative of MAME, and contains various hacks and homebrews | | [higan Accuracy](../library/higan_accuracy.md) | Nintendo SNES/SFC/Game Boy/Color | | | [Holani](../library/holani.md) | Atari Lynx | | | Imageviewer | Imageviewer | A basic core for viewing still images in a libretro frontend | | Ishiiruka | Nintendo GameCube/Wii | | | JAXE | CHIP-8/S-CHIP/XO-CHIP | | | [JollyCV](../library/jollycv.md) | ColecoVision/CreatiVision/My Vision | | | Jump 'n Bump | Game engine | A reimplementation of the engine of Jump 'n Bump, a open-source MS-DOS multiplayer video game by Brainchild Design | | Kronos | Sega Saturn/ST-V | A port of the Kronos, which is itself a fork of Yabause emulator | | LowRes NX | Game engine | A port of the LowRes NX fantasy console to libretro | | Lutro | Game engine | An experimental Lua game framework for libretro, based on a subset of the LOVE API | | M2000 | Philips P2000T | A port of M2000, the portable Philips P2000 emulator to libretro | | MAME (Current) | Arcade/Console/various | Based on MAME development branch. Full list of supported systems: http://adb.arcadeitalia.net/mame.php | | MAME 2000 | Arcade/Console/various | (See MAME note) | | [MAME 2003](../library/mame_2003.md) | Arcade/Console/various | (See MAME note) | | MAME 2003 Midway | Arcade/Console/various | (See MAME note) | | [MAME 2003-Plus](../library/mame2003_plus.md) | Arcade/Console/various | (See MAME note) | | MAME 2009 | Arcade/Console/various | (See MAME note) | | [MAME 2010](../library/mame_2010.md) | Arcade/Console/various | (See MAME note) | | MAME 2015 | Arcade/Console/various | (See MAME note) | | MAME 2016 | Arcade/Console/various | (See MAME note) | | [melonDS 2021](../library/melonds.md) | Nintendo DS | | | [melonDS DS](../library/melonds_ds.md) | Nintendo DS/DSi | Enhanced remake of the melonDS core based on a newer version of the emulator. | | [Mesen](../library/mesen.md) | Nintendo NES/Famicom | | | [Mesen-S](../library/mesen-s.md) | Nintendo SNES/SFC/Game Boy/Color | | | MESS 2015 | Multi (various) | (See MAME note) | | [Meteor](../library/meteor.md) | Game Boy Advance | | | [mGBA](../library/mgba.md) | Game Boy Advance | | | Microw8 | Game engine | A port of a WebAssembly based fantasy console to libretro | | [Minivmac](../library/minivmac.md) | Mac II | MacII variant of minivmac emulator | | [mkxp-z](../library/mkxp-z.md) | RPG Maker XP/VX/VX Ace | | | mpv | Media player | An port of MPV media player to libretro | | Mr.Boom | Game | A clone of the classic Bomberman series | | Mu | Palm OS | An emulator for the Palm m515 OS ported to libretro | | [Mupen64Plus-Next](https://docs.libretro.com/library/mupen64plus/) | Nintendo 64 | | | [Mupen64Plus-Next GLES2](https://docs.libretro.com/library/mupen64plus/) | Nintendo 64 | | | [Mupen64Plus-Next GLES3](https://docs.libretro.com/library/mupen64plus/) | Nintendo 64 | | | Neko Project II | NEC PC-98 | | | Neko Project II Kai | NEC PC-98 | | | NeoCD | Neo Geo CD | | | [Nestopia](../library/nestopia.md) | Nintendo NES/Famicom | | | [nSide Balanced](../library/nside_balanced.md) | Nintendo SNES/SFC/Game Boy/Color | | | Numero | TI-83 | A TI-83 Emulator for Libretro | | NXEngine | Game engine | An open-source reimplementation of the Cave Story / Doukutsu engine | | O2EM | Magnavox Odyssey2/Philips Videopac+ | | | Oberon | Oberon RISC machine | An emulator for the Oberon RISC machine, ported to libretro | | OpenLara | Game engine | A port of the OpenLara free/open re-implementation of the engine used by the original Tomb Raider series | | OpenTyrian | Game | A port of the OpenTyrian clone of the classic Tyrian shmup, ported to libretro | | [Opera](https://docs.libretro.com/library/opera/) | 3DO | | | ParaLLEl N64 | Nintendo 64 | | | PascalPong | Game | A free and basic clone of the classic Pong game, written for libretro | | PCem | IBM PC | | | [LRPS2](https://docs.libretro.com/library/lrps2/) | Sony PlayStation 2 | | | [PCSX ReARMed](https://docs.libretro.com/library/pcsx_rearmed/) | Sony PlayStation | | | [PD777](../library/pd777.md) | Epoch Cassette Vision | | | PicoDrive | Sega MS/GG/MD/CD/32X | | | Play! | Sony PlayStation 2 | | | Pocket CDG | Karaoke player | A karaoke music player, ported to libretro | | [PokeMini](../library/pokemini.md) | Nintendo Pokemon Mini | | | Potator | Watara Supervision | | | PPSSPP | PlayStation Portable | | | PrBoom | Game engine | A port of the PrBoom source port of iD's classic Doom engine | | [ProSystem](../library/prosystem.md) | Atari 7800 | | | [PUAE](../library/puae.md) | Commodore Amiga | | | [PUAE 2021](../library/puae.md) | Commodore Amiga | | | PuzzleScript | Game engine | A port of PuzzleScript, open source HTML5 puzzle game engine | | PX68k | Sharp X68000 | | | QUASI88 | NEC PC-8000/PC-8800 series | | | [QuickNES](../library/quicknes.md) | Nintendo NES/Famicom | | | RACE | Neo Geo Pocket/Color | | | Redbook | Music player | A libretro core for playing back Redbook-formatted audio, such as commercial audio CDs | | REminiscence | Game engine | A port of the REminiscence engine, a reimplementation of the engine used by Delphine Software's Flashback | | Retro8 | Game engine | A port of the Retro8 open-source reimplementation of the PICO-8 fantasy console to libretro | | Rustation | Sony PlayStation | | | RVVM | RISC-V Virtual Machine | | | [SameBoy](../library/sameboy.md) | Game Boy/Color | | | SameDuck | Mega Duck (Cougar Boy) | An adaptation of SameBoy to play Mega Duck games | | [SAME CDI](../library/same_cdi.md) | Philips CDi | SAME CDi is a S(ingle) A(rcade) M(achine) E(mulator) for libretro, forked from MAME, which only includes the Philips CD-i driver | | [ScummVM](https://docs.libretro.com/library/scummvm/) | Game engine | A fork of the ScummVM adventure game engine ported to libretro | | SimCoupe | SAM Coupe | | | [SMS Plus GX](https://docs.libretro.com/library/smsplus/) | Sega MS/GG | | | [Snes9x](https://docs.libretro.com/library/snes9x/) | Nintendo SNES/SFC | | | [Snes9x 2002](https://docs.libretro.com/library/snes9x_2002/) | Nintendo SNES/SFC | | | [Snes9x 2005](https://docs.libretro.com/library/snes9x_2005/) | Nintendo SNES/SFC | | | [Snes9x 2005 Plus](https://docs.libretro.com/library/snes9x_2005_plus/) | Nintendo SNES/SFC | | | [Snes9x 2010](https://docs.libretro.com/library/snes9x_2010/) | Nintendo SNES/SFC | | | SquirrelJME | Java ME | A port of the SquirrelJME Java ME 8 Virtual Machine emulator to libretro | | [Stella](https://docs.libretro.com/library/stella/) | Atari 2600 | | | Stella 2014 | Atari 2600 | | | Super Bros War | Game engine | A fork of Super Mario War, a fan-made multiplayer Super Mario Bros. style deathmatch game | | SwanStation | Sony PlayStation | SwanStation is a fork of the Duckstation emulator | | [TempGBA](https://docs.libretro.com/library/tempgba/) | Game Boy Advance | | | [TGB Dual](https://docs.libretro.com/library/tgb_dual/) | Game Boy/Color | | | [Theodore](https://docs.libretro.com/library/theodore/) | Thomson MO/TO | | | TIC-80 | Game engine | A port of the free and open source fantasy computer TIC-80 to libretro | | The Powder Toy | Game | A port of the Powdertoy physics sandbox/simulation engine to libretro | | [TyrQuake](https://docs.libretro.com/library/tyrquake/) | Game engine | A port of the tyrquake engine | | UAE4ARM | Commodore Amiga | | | UME 2015 | Arcade/Console/various | (See MAME note) | | Uzem | Uzebox | A port of Uzem, the official emulator for the Uzebox | | VaporSpec | Game engine | A virtual game platform with capabilities similar to 80s game consoles | | [VBA-M](../library/vba_m.md) | Game Boy Advance | VisualBoy Advance-M is a active fork of VisualBoy Advance emulator | | [VBA Next](https://docs.libretro.com/library/vba_next/) | Game Boy Advance | | | [vecx](../library/vecx.md) | GCE/MB Vectrex | | | [VeMUlator](https://docs.libretro.com/library/vemulator/) | SEGA Visual Memory Unit | A port of VeMUlator, a SEGA Dreamcast VMU emulator originally developed for Android | | [VICE x64](../library/vice.md) | Commodore C64 | | | [VICE x64dtv](../library/vice.md) | Commodore C64DTV | DTV2 PAL/NTSC, DTV3 PAL/NTSC, HUMMER NTSC | | [VICE x64sc](../library/vice.md) | Commodore C64 | | | [VICE x128](../library/vice.md) | Commodore C128 | | | [VICE xcbm2](../library/vice.md) | Commodore CBM-II 6x0/7x0 | | | [VICE xcbm5x0](../library/vice.md) | Commodore CBM-II 5x0 | | | [VICE xpet](../library/vice.md) | Commodore PET | | | [VICE xplus4](../library/vice.md) | Commodore Plus/4 | | | [VICE xscpu64](../library/vice.md) | Commodore C64 SuperCPU | | | [VICE xvic](../library/vice.md) | Commodore VIC-20 | | | Vircon32 | Game engine | A port of Vircon32 game console to libretro | | [Virtual Jaguar](../library/virtual_jaguar.md) | Atari Jaguar | | | [VirtualXT](../library/virtualxt.md) | DOS | Runns PC/XT class software. Mainly intended for PC booters from the 80's. | | vitaQuake 2 | Game engine | A port of the VitaQuake 2 source port of iD's Quake 2 engine to libretro. There is a separate core for each of the Quake 2 mission packs, 'Rogue', 'Zaero' and 'Xatrix'. | | vitaQuake 2 (Rogue) | Game engine | (See vitaQuake 2 note) | | vitaQuake 2 (Xatrix) | Game engine | (See vitaQuake 2 note) | | vitaQuake 2 (Zaero) | Game engine | (See vitaQuake 2 note) | | vitaQuake 3 | Game engine | A port of the VitaQuake 3 source port of iD's ioquake3 engine to libretro | | vitaVoyager | Game engine | A port of the Lilium Voyager engine, which runs the Star Trek: Voyager - Elite Force game and is itself based on the ioquake3 | | WASM-4 | Game engine | WASM-4 is a open source low-level fantasy game console for building small games with WebAssembly | | X Millennium | Sharp X1 | | | XRick | Game engine | A port of the XRick, an open-source clone of the Rick Dangerous engine | | YabaSanshiro | Sega Saturn | A port of the YabaSanshiro, which is itself a fork of Yabause emulator | | Yabause | Sega Saturn | | ================================================ FILE: docs/guides/crtswitchres.md ================================================ # CRTSwitchRes [Switchres](https://github.com/antonioginer/switchres) is a modeline generation engine for emulation. Its purpose is on-the-fly creation of fully customized video modes that accurately reproduce those of the emulated systems. Based on a monitor profile, it will provide the best video mode for a given width, height, and refresh rate. The usual motivation is to connect a CRT display and have it driven in the original resolution (at least vertically), which is otherwise too low for modern display systems. The connection is typically from a digital connector (such as HDMI) on the computer side and needs an external converter for the CRT. ## Setup ### Windows AMD video card is needed. Windows works the best with CRT Emudriver, available [here](http://geedorah.com/eiusdemmodi/forum/viewtopic.php?id=295). Once you have this setup and running, it is a simple case of turning CRTSwitchRes on and choosing your settings. Other options are available. It's a simple case of getting the resolutions installed on you Windows PC. ### Linux Switchres can work in the following environments: - X11 - KMS mode - Raspberry Pi with legacy graphics drivers !!! note In some cases your distribution may be missing some X libraries in this case make sure you install the following `libx11-dev libxrandr-dev` !!! note The composite output of RPi has fixed resolution and is unsuitable for custom modelines. ## Enabling and Changing Settings CRTSwitchRes now using Switchres by Calamity. This is available on both Windows and Linux. To enable CRTSwitchRes or change settings - Navigate to **Settings** - Navigate to **Video** - Navigate to **CRT SwitchRes** !!! tip CRTSwitchRes is hidden behind advanced settings. Please enable advanced settings in User Interface first. ## CRTSwitchRes Options | Option | Available Values | | ----------------------- |:-----------------------------------------------:| | CRT SwitchRes | off, 15KHz, 31KHZ Standard, 31KHZ- 120Hz, INI | | CRT Super resolution | Native, Dynamic, 1920, 2560, 3840 | | X Centering | Currently not in use | | Porch Adjust | Currently not in use | | Use Custom refresh rate | Currently not in use | ## Option 1. CRT SwitchRes This option is where you will turn on SwitchRes and choose your main output hardware. | CRT SwitchRes Value | Description | | ----------------------- |:----------------------------------------------------------------------------------------:| | off | This setting turns SwitchRes off | | 15KHz | This will request SR to be setup for 15KHz monitors/TVs output | | 31KHz | This will request SR to be setup to output for 31KHz monitors/TVs output | | 31KHz, 120z | This will request SR to be setup to output for 31KHz @120HZ monitors/TVs output for 240p | | INI | This will request SR to look at the switchres.ini for the monitors/TVs output | !!! tip This can not be changed on-the-fly once SwitchRes is active. This setting will take effect after a restart. ## Option 2. CRT Super Resolution | CRT Super resolution values | Description | | --------------------------- |:------------------------------------------------------:| | Native | This will pass the cores native resolution to SR | | Dynamic | Currently not in use | | 1920 | This will pass a hard set super width of 1920 to SR | | 2560 | This will pass a hard set super width of 2560 to SR | | 3840 | This will pass a hard set super width of 3840 to SR | !!! note All resolution are integer scaled and aspect ratio corrected to match the original resolution. Unless you really need a locked super width only choose native and let SR do all the work. Even if your monitor does not support native resolutions, the best option to choose will be Native. For Windows, SwitchRes will look for compatible modes with and without super widths. For Linux, you can add the switchres.ini **(see Advanced Settings below)** into you RetroArch folder. Edit this file and change the dotclock_min form 0 to 25.0. This will then calculate dynamic super widths for cards that do not support low dotclocks (native widths produce low dotclocks). ## Advanced Settings As CRTSwitchRes is now using Switchres by Calamity, there are many options to customise you environment within the switchres.ini. However, some options are available with the CRTSwitchRes settings menu in RetroArch. Although more settings can be set in the switchres.ini, it is not a required step. It does however allow for more customisation. For more details on how to configure and use the switchres.ini, [go here](https://gitlab.com/groovyarcade/support/-/wikis/3-Post-Installation-and-Maintenance/3.9-Configure-System-Wide-Switchres). Currently, the switchres.ini is not supplied with RetoArch. This will change in the near future. In the meantime you can download this file from [here](https://raw.githubusercontent.com/antonioginer/switchres/master/switchres.ini). !!! Note A default switchres.ini file will be searched in the current working directory, then in .\ini on Windows, ./ini then /etc on Linux. The repo has a switchres.ini example. ## CRTSwitchRes Options Via retroarch.cfg | Config Option Name | Description | Values | | ----------------------------------------------- |:------------------------------------------------------:|:--------------------------------:| | crt_switch_center_adjust | Currently not in use | | | crt_switch_porch_adjust | Currently not in use | | | crt_switch_resolution | Same as above **CRT SwitchRes** | 0,1,2,3,4 - off, 15kHz, 31kHz Standard, 31kHz- 120Hz, INI respectively | | crt_switch_resolution_super | Same as above **CRT Super Resolution** | Native, Dynamic, 1920, 2560, 3840| | crt_switch_resolution_use_custom_refresh_rate | Not currently in use | false | | crt_switch_timings | Do not change | | | crt_video_refresh_rate | Do not change | Set by SwitchRes | ## Core and directory overrides If you are using a `switchres.ini` configuration file and wish to fine-tune specific setting for certain cores or directories, it is possible to use core and directory overrides for this. These files can be placed at the same locations as the usual `.cfg` files for RetroArch's core and directory overrides, only replacing the `.cfg` with `.switchres.ini`. For example, if you are using native resolution on your configuration but want to user a 2560 super resolution on the Gambatte core, you can create the file `CONFIG_DIR/config/Gambatte/Gambatte.switchres.ini` with the content `user_mode 2560x0` in it. This setting will override the one on the original switchres.ini file when running this specific core. When closing this core, or switching to a different core, the default `switchres.ini` file will be re-loaded to undo the change. The same works for directory overrides. Example: If you want to use a super resolution of 2560 for roms in the "Sega - Game Gear" directory, while using the Genesis Plus GX core, you can create an override. Create the file `CONFIG_DIR/config/Genesis Plus GX/Sega - Game Gear.switchres.ini` and add the user mode to that file. !!! note You have to be using a full, complete `switchres.ini` base file for the overriding files to work properly, otherwise overriding settings will persist until you restart RetroArch. ================================================ FILE: docs/guides/databases.md ================================================ # Databases RetroArch uses `.rdb` [database format](https://github.com/libretro/RetroArch/blob/master/libretro-db/README.md) files stored locally by default in folder `RetroArch/databases`. The `.rdb` files are compiled from clrmamepro format `.dat` files stored at the [libretro database repository](https://github.com/libretro/libretro-database). See the database [readme](https://github.com/libretro/libretro-database/blob/master/README.md) for comprehensive information about the sources and functioning of the repository. !!! Hint "Terminology Note: Game Name" The term _Game Name_ refers to the name displayed [within the RetroArch interface and in playlists](https://docs.libretro.com/guides/roms-playlists-thumbnails/#retroarch-playlist-scanner), _not_ to the filename of the underlying file on the computer or device. _Game Name_ in this document is synonymous with playlist item label, playlist entry, content name, and game title. ## Features of RetroArch Database Usage RetroArch uses the database to provide several automated cataloging functions: - __Validation__. Reject or accept files when using the [Import Scanner / Playlist Generator](https://docs.libretro.com/guides/roms-playlists-thumbnails/#working-with-playlists) based on whether the ROM checksum (or [other key](#key-field-for-matching)) matches the checksum of a known verified completely intact (aka "properly dumped") file in the database. - __Game Naming__. Assign a definitive and uniform display name for each game in a playlist regardless of filename. RetroArch will look up the `name` field specified for the file's [key](#key-field-for-matching) in the database. - _Secondary_: __Thumbnail Images__. Download and display thumbnail images for games based on the uniform name assigned by the database, regardless of filename. (Thumbnails are __not__ directly assigned by the database or by checksum association, but as a secondary effect of databased *game name* assignment if a matching thumbnail is available on the server. Also see: [Flexible Name Matching Algorithm](https://docs.libretro.com/guides/roms-playlists-thumbnails/#custom-thumbnails).) - __Category Search ("Explore")__. Allows the user to find/view games that match selected criteria, e.g. by Developer, Release Year, Genre, and other attributes/metadata. - __Per-Game Information View__. Provide an in-app viewable informational screen for each game (Game > Information > Database Entry). ## How the Import Scanner Uses the Database _See also: [Importing Content](https://docs.libretro.com/guides/import-content/) and [Creating Playlists](https://docs.libretro.com/guides/roms-playlists-thumbnails/#retroarch-playlist-scanner)._ RetroArch's Import Content actions "Directory Scan" and "File Scan" will do the following: 1. Compute a CRC checksum of the file(s) or scan for the in-game serial number. CRC and serial number are the [keys used for matching a game file to the database](#key-field-for-matching). 1. Search for that CRC or serial in the information of the local `.rdb` files (default location `RetroArch/databases`). If the key is not found in databases, the file will __not__ be added to a playlist. See [Validation & Rejection](#validation-and-rejection). 3. Assign the `Game Name` (aka display name or playlist item name) that is specified as `name` within the database entry for the key (CRC/serial). The assigned `Game Name` will appear in the playlist, instead of the filename. 4. All other associated metadata [collated in the .rdb](https://github.com/libretro/libretro-database#fields-specified-in-game-information-databases) entry for the given CRC/serial can be viewed in the Information > Database Entry for the game and will be viewable via "Explore". ### Validation and Rejection Validation here refers to checking a file or attribute against a reference, and then accepting or rejecting it based on whether it matches what is specified in the reference data (aka what is "allowed"). RetroArch's "Scan Directory" and "Scan File" automated importers are validation processes, not merely tools for adding all files to a playlist. Part of their function is to **reject** files, not to import all files. The database is the reference, and the ROM file is the item being validated. If your file's crc or internal serial data (whichever is the key used for matching, [see below](#key-field-for-matching)) does not exist in the database, the file will be rejected by the automatic scans and will not appear in the playlist. __Bypass validation and rejection.__ To import your games into a playlist regardless of database matches, or if your files are being rejected by the automatic scan (in other words are not recognized by the database) and you wish to add them to the playlist anyway, use the [Manual Scan](https://docs.libretro.com/guides/roms-playlists-thumbnails/#working-with-playlists). ### Key Field for Matching During [Playlist / Import Scanning](https://docs.libretro.com/guides/roms-playlists-thumbnails/#retroarch-playlist-scanner) ("Directory Scan" and "Scan File" in menu), RetroArch will identify your _files_ in order to then match your file to a data entry in the database. The key for matching varies by console typical file size (i.e. original media type). - __CRC checksum__ for systems with smaller file sizes, e.g. games before the advent of disc-based consoles. - __Serial Number__ for larger files like disc-based games, to avoid computing checksums on large files. Found within the ROM file. The serial is not metadata but encoded within the game's binary data, which is scanned (in applicable cases) as a byte array by RetroArch. Contrary to popular belief, the data used for matching is often the _serial number_ encoded within a disc-game's binary data. Databases include cryptographic hashes (sha1, etc) for informational purposes to define the item specified, but only CRC checksum (or serial) not hashes are used for matching. ## Databases and Thumbnails Thumbnails _are not_ assigned or retrieved based on checksum, serial, or game database matching. See separate documentation for [thumbnail handling](https://docs.libretro.com/guides/roms-playlists-thumbnails/#thumbnails) and the thumbnail [matching algorithm](https://docs.libretro.com/guides/roms-playlists-thumbnails/#custom-thumbnails). Currently there is no _automatic_ process that applies database game name changes/updates to libretro [thumbnail repository](https://github.com/libretro-thumbnails/libretro-thumbnails) image filenames. Therefore one of the visible consequences of a Game Name or database problem is the lack of an appropriate thumbnail display in RetroArch whenever the `Game Name` displayed in the interface doesn't match a repository thumbnail filename. - __Game name error__. To help fix a database error where the game name doesn't match a correctly named thumbnail in the repository, see [How to Contribute to Databases](#how-to-contribute-to-databases). - __Thumbnail name error__. To help fix a thumbnail in a case where a _correct_ database game name doesn't match the repository thumbnail name, follow the [Thumbnail Repository readme](https://github.com/libretro-thumbnails/libretro-thumbnails/blob/master/README.md#contributions) and [How To Contribute Thumbnails guide](https://docs.libretro.com/guides/roms-playlists-thumbnails/#contributing-thumbnails-how-to). ## Troubleshooting _See also: RetroArch documentation for [Import Scanning](https://docs.libretro.com/guides/import-content/) and [Playlist Creation/Scanning](https://docs.libretro.com/guides/roms-playlists-thumbnails/#retroarch-playlist-scanner)._ The information below is for Users who are interested in figuring out the cause of a database-related problem and possibly helping to fix the problem in a way that will help all users. RetroArch is a volunteer project, and many problem situations can be improved by interested users with medium technical awareness and no programming skill needed. ### Common Problems and Solutions The most common user problems and solutions related to the database are: - __Missed files during import scan.__ I.e. automated Directory Scan or File Scan "misses" some files, meaning the files are not imported and do not appear in the playlist. See [Validation & Rejection](#validation-and-rejection) above. - Solution A: [Contribute to the database](#how-to-contribute-to-databases) with data for the files/games that are not yet covered by the database. - Solution B: Use the __Manual Scan__ option, which will accept all files according to the chosen settings. - __Game Name error or incorrect information__. E.g. A game file receives a wrong title inside the RetroArch playlist/interface. - Solution: - Follow the [investigation steps](#investigating-database-issues) below to find the `.dat` file that has the erroneous information, and [contribute a correction](#how-to-contribute-to-databases). - Depending on the source of the data, an upstream change within a database group's system may be required, but it is also possible to create ad hoc database coverage on the libretro github. - __Outdated Local Files__. I.e. an error(s) has been fixed in the libretro database but the fix has not yet been downloaded in the user's app install. - Solution: Update your RetroArch databases (Main Menu > Online Updater > Update databases). That will apply recent fixes/corrections to your RetroArch install. ### Investigating Database Issues Follow the steps below to find the cause of a database or game/name identification issue: - __Learn about the factors that might be causing the Problem__ - Understand the multifaceted [.dat system](https://github.com/libretro/libretro-database#retroarch-database) and files. Multiple different .dat files may have data for the same game. - Understand [which key field](#key-field-for-matching) RetroArch uses for identifying your file and for searching for your file's info in the database. - Understand [precedence](https://github.com/libretro/libretro-database#precedence) within the dat files in the repository. - __Verify data "on both sides"__ - __Verify your file properties.__ Verify your game file has the appropriate [key ID](#key-field-for-matching): compute the crc checksum, or verify the encoded serial number with a hex editor, whichever is applicable. - __Verify libretro databases on github__. Look in the repository databases to find which `.dat` file might hold incorrect data for the game file at issue. Even if you find a `.dat` that holds correct data for the game key (CRC or serial) in question, a different dat with [precedence](https://github.com/libretro/libretro-database#precedence) may hold incorrect data that is over-ruling the correct data. - __Verify upstream data__ to find mismatches or pending corrections. If an upstream database group (No-Intro, Redump, GameTDB, etc) is [responsible for the `.dat` at issue](https://github.com/libretro/libretro-database#sources), look on their websites to see whether their current information is correct or incorrect. ### Help Fix the Problem After you've investigated the issue (see above), some possible actions are: - __Update__. Use _Main Menu > Online Updater > Update Databases_ to download new and possibly corrected data from the libretro server. - __[Contribute](#how-to-contribute-to-databases)__ a correction or addition of data to fix the issue. It may be possible to create an ad hoc database or to make a new entry within an existing ad hoc database. - __Use the [Issue Tracker](https://github.com/libretro/libretro-database/issues)__. - __Search__ for existing issues on github that may hold useful advice or solutions for your problem. Adding your new examples or insights to the discussion for the problem may help Members/Contributors create a fix. - __Open__ an Issue if a relevant one isn't already open. - Open a [Database Issue](https://github.com/libretro/libretro-database/issues) __if__ you observe either of the following: - You see a large-scale issue affecting many data entries or entire dats. - You found that Upstream Data is _correct_ but libretro or RetroArch doesn't reflect it, and at leat 4 weeks have passed since the Upstream update occurred. - Open a [RetroArch Issue](https://github.com/libretro/RetroArch/issues) __if__: you see a problem with RetroArch's scanning behavior or validation, while the databases appear correct and match your file's properties (crc and serial within the game's binary data viewable with a hex editor). - __Submit Upstream Changes.__ Make changes upstream (No-Intro, Redump, GameTDB, etc) by going through the channels of the upstream group responsible for the data at issue __if__: you found that Upstream Data is _Incorrect_ and has been imported to the libretro database repository. The upstream group must make the correction to "fix it at the source", though it may be possible to create alternative data coverage instead (see below). ## How to Contribute to Databases Like [thumbnails](https://docs.libretro.com/guides/roms-playlists-thumbnails/#contributing-thumbnails-how-to) and [documentation](https://docs.libretro.com/meta/how-to-contribute/), databases are an area where users who are not programmers can contribute to RetroArch and in a way that benefits all users. ### Github Steps Overview 1. Make an account on github.com and login. 2. Fork the libretro database repository. Forking means copying the repository into your own working area on github. 3. Make your changes within your fork. For example, create a new `.dat`, or add a game entry or correction to an existing dat. - Understand the principles and [header specifications](https://github.com/libretro/libretro-database#header-guidelines-for-dats) explained in the [database repository readme](https://github.com/libretro/libretro-database#). - Carefully heed the existing formats observable in present `.dat` files on the repository. 5. "Commit" (save) your changes with your fork. 6. Use the "Pull Request" button (or the Contribute > Open Pull Request button) to send and propose your changes to the libretro official team members. They will review your contribution, and in time either accept it or inform you about required changes or a reason why it isn't acceptable. ### Small-Scale Corrections See [database repository readme](https://github.com/libretro/libretro-database#small-scale-corrections) to learn when/where small-scare corrections are appropriate. Two methods for adding data coverage for a single game or niche of games, via Pull Request proposal on github: - __Method A:__ Fix the dat at issue. This is only possible if two conditions are met: - 1. The `.dat` doesn't originate from an import from upstream _and_ - 2. The `.dat` won't receive subtractive sync over-writes in the future. - _If those conditions are not met, the intended "fix" would be deleted by the next bulk import sync._ _Or..._ - __Method B:__ Edit a different dat, leaving the erroneous dat intact but moot. This is only advisable when the correction and the error have different [keys](#key-field-for-matching), or if the edited/corrected database has [precedence](https://github.com/libretro/libretro-database#precedence) over the erroneous database. If one of those conditions is _not_ met, then the attempted correction would fail: it would be over-ruled in the `.rdb` compile by the erroneous dat's information. If one of those conditions is met, you may do one of following: - Add a game data entry to an existing and appropriate ad hoc `.dat` in the repository. - Create a new ad hoc `.dat`. This is often acceptable even for a small number of games because of the multi-faceted nature of the dat system. Some limitations may be enforced by admins, e.g. for the manageability of the build script or the repository. ### Large-Scale Additions See [Adding New Database](https://github.com/libretro/libretro-database#adding-a-new-database). Contributors are welcome to propose the addition of bulk data from their own build scripts or otherwise, via github Pull Request. ================================================ FILE: docs/guides/disc-swapping.md ================================================ # Disc swapping Some games in the 32-bit generation were spread over multiple CDs, and at a certain point in the game they ask the user to swap one disc out for another, while the console is still powered on. To manage discs, libretro has a concept of a disc index (like a multi-disc CD player). If a Sony PlayStation core or Sega Saturn core is loaded, then a `Disc Control` option is added to the [Quick Menu](quick-menu.md). ## Using 'Eject/Load disc' `Load New Disc` ejects the current (virtual) disc and opens the File Browser, where you can select a new disc image to be loaded. When you select `Eject Disc`, three new options appear: * `Insert Disc`: Opens the File Browser, to find a disc image and load it into the Disc Index (CD list). * `Current Disc Index`: Displays a list of the current discs in the "CD changer", and lets you select which disc is "in use". * `Load New Disc`: Opens the File Browser, to find another disc image and load it into the Disc Index (CD list). ## Using 'Disc Image Append' If you don't or can't use a playlist, you can append a disk image to the list on the fly using `Disc Image Append`. In this case, you use the File Browser to look for a disk image, and then add it to the internal disk image list. The `Disc Index` list is updated appropriately, and you can make your selection then return to the game. ## Using M3U playlists Multi-CD images are typically handled with an .m3u playlist file. In this case, you can swap disks by cycling through the `Disc Index` setting. You can start a game by loading its M3U file, through `Load Content` or Playlists (This will have to be added manually to your Playlists, as scanning for content will not do so). ### Making an M3U playlist file You can make an M3U playlist file using a simple text editor. * Put all of your content's disc files into a single folder. * Create a new text file in the same folder as your content. Name it the same as your content. * Add the full names of each disc into the text file (including the file extension), 1 filename per row. * If your discs are BIN/CUE files, only list the '.cue' files in the document. * If your discs are CHD files, list the '.chd' files in the document. * Save and close the text file. * Rename the file extension from '.txt' to '.m3u'. #### Example Contents of folder (`ROMS/Metal Gear Solid/`): *** Metal Gear Solid (USA) (Disc 1).bin
Metal Gear Solid (USA) (Disc 1).cue
Metal Gear Solid (USA) (Disc 2).bin
Metal Gear Solid (USA) (Disc 2).cue
Metal Gear Solid (USA).m3u *** Contents of M3U file (`Metal Gear Solid (USA).m3u`): *** Metal Gear Solid (USA) (Disc 1).cue
Metal Gear Solid (USA) (Disc 2).cue *** ## Issues and workarounds Replacing the disk inside RGUI is "physically" speaking the same as ejecting, swapping disks and closing the tray instantaneously. Some games will not work with this approach: Notably *Metal Gear Solid* needs to detect an actual "eject" taking place. To work around this, set `Disk Index` to `No Disk`, and exit RGUI. The game will pick up that the tray has been ejected/missing disk after half a second or so. Now you can go back to RGUI, pick the correct disk index and return to the game. ================================================ FILE: docs/guides/download-cores.md ================================================ # Cores Cores are essentially other programs and games that run through RetroArch. RetroArch requires cores to run any content. !!! tip Many game console may have multiple emulator cores, the question of which one is the best may come up. Emulators can be designed to be more accurate at the cost of a performance hit, check out the Emulation General Wiki for a good look at what will suit your needs and hardware. ## Installing cores through RetroArch interface !!! tip If you do not see the "Core Downloader" option, you may have installed RetroArch using a package manager. If so, see [Installing cores through package manager (Ubuntu PPA only)](#installing-cores-through-package-manager-ubuntu-ppa-only). Otherwise, to enable it: - Navigate to **Settings** - Navigate to **User Interface** - Navigate to **Menu Item Visibility** - Enable **Show Core Downloader** ![Core Downloader](../image/retroarch/ozone/core_downloader.gif) - Navigate to **Online Updater** - Navigate to **Select Core Downloader** - Select the core you want to download !!! note If you're using the Ubuntu PPA version of RetroArch and have enabled "Show Core Downloader" manually, your changes will not be reflected unless your the Cores directory setting is set to a writable location in the [Directory Configuration](change-directories.md#cores). ## Installing cores through package manager (Ubuntu PPA only) !!! note Installing RetroArch through the Ubuntu PPA will disable the "Core Downloader" option in RetroArch's interface, therefore core installation needs to happen through the Ubuntu package manager. - Open a terminal - Start typing **sudo apt-get install libretro-** - Press tab a few times until all available possibilities show, press space to expand the list. - Now type the full name of the core you want to install *Example: sudo apt-get install libretro-nestopia* - Press enter and follow the process to install ================================================ FILE: docs/guides/file-browser.md ================================================ # File Browser For this part of the setup guide we will be teaching you how to use RetroArch's file browser. The browser is rather basic, although it isn't too hard to get used to it. ## Change default directory To make your content easier to get to, you should change the default directory. This would be a good first use of the file browser. Move to the settings tab then find **Directory**, then move to **File Browser**. The first screen should show the storage devices move to the one that contain your game content and press enter. ![Storage Devices](../image/retroarch/ozone/ozone_directory1.jpg) !!! note On Windows it will display drive letters (like C:/ and D:/), However a system like Linux doesn't work in the same way and will only display the root. Most Android users should select */storage/emulated/0* if they want internal storage. You have now entered the main part of the file browser. Beneath the first two options will be all your folders. Navigate your file system until you are inside your content folder then select **<Use this directory>**. !!! tip On GNU/Linux, other hard drives are usually stored under */media/* or */mnt/*. ![File System](../image/retroarch/ozone/ozone_directory2.jpg) You should now be back in the settings menu with the *File browser* set to the folder you wanted. ================================================ FILE: docs/guides/generating-retroarch-logs.md ================================================ ## What are logs? Why are they so important? RetroArch and its underlying libretro technology is designed to run on many different combinations of hardware, operating system, libretro core, and content. It is not possible for a volunteer-based open source project to test all possible combinations. The answer to this dilemma involves "logs", which RetroArch and other libretro software use to record essential information about your system and its function that other users and volunteers need in order to help troubleshoot problems and improve compatibility with new systems. -------------------------- ## Generating Logs ### Generating Logs via Menu 1. Go to "Settings" 2. Enter "Logging" 3. Activate "Logging Verbosity" 4. Activate "Log to File" 5. (optional) Adjust "Frontend / Core Logging Level" to get more or less detailed information 6. (optional) Activate "Timestamp Log Files" if you don't want to overwrite the log at each startup This will place the logs in the System Events Logs directory, visible in the "Directory" settings. ### Generating Logs in Lakka [Please see the Troubleshooting Lakka doc](http://www.lakka.tv/doc/Troubleshooting-Lakka/). ### Generating Logs in Linux #### RetroArch logs 1. Open a terminal. 2. Navigate to the RetroArch folder with the `cd` command. 3. Start RetroArch in 'verbose' mode with this command:
`retroarch -v --log-file retroarch.log` or `retroarch -v >> retroarch.log 2>&1` 4. Once you exit RetroArch, a file called `retroarch.log` should be stored in the folder. #### Graphic card logs `lspci -nnk | grep -A 3 VGA` will give information about your graphic card. #### Audio device logs `aplay -L` enumerates audio devices which have been detected. #### Input device logs `lsusb` lists all devices attached via USB `dmesg` displays all messages from the kernel ring buffer which typically is holding the messages generated by the Linux kernel from the boot process. The dmesg log lists each hardware device that the kernel detected along with information on how the device was configured by the system. ### Generating Logs in Windows !!! tip You can hold `shift` then `right click` on the **folder that contains** retroarch.exe
Select `Open PowerShell window here`.
In the PowerShell window, use the `cmd` command to switch to the Windows console. Then jump to step 3. 1. Open a console window with the `cmd` command, found either in the Start Menu or through use of the Windows "Run" menu. 2. Navigate to the RetroArch folder using the `cd` command. 3. Start RetroArch in 'verbose' mode with this command:
`retroarch.exe -v --log-file retroarch.log` or `retroarch.exe -v >> retroarch.log 2>&1` 4. Once you exit RetroArch, a file called `retroarch.log` should be stored in the folder. ### Generating Logs in OS X 1. Open a console window with the OS X "Terminal" app. 2. Navigate to the RetroArch.app folder using the `cd` command. 3. Inside the RetroArch.app folder, navigate to the Contents/MacOS filter. 4. Start RetroArch in 'verbose' mode with this command:
`./RetroArch -v --log-file ~/retroarch.log` or `./RetroArch -v >> ~/retroarch.log 2>&1` 5. Once you exit RetroArch, a file called `retroarch.log` should be stored in your home directory. ### Generating Logs in Android There is a range of variation in the logging systems available to Android device depending on the combination of hardware and operating system in use. There are two general approaches to generating logs in Android: tethering to a PC via a USB cable or using a `logcat` app. #### Generating Logs via USB Tether **Prerequisites**: * Linux, Windows or Mac PC * USB cable for your device **Instructions**: * Install your device driver for using adb on your PC from http://developer.android.com/tools/extras/oem-usb.html * Download the adb executable for your OS -- it can be downloaded as part of the [full Android SDK](https://developer.android.com/studio/index.html), but you might also be able to find the adb executable individually. * Connect your Android device to the PC via USB cable. * Enable the developer options on the Android. * Enable USB debugging on the Android. * Open a command prompt (Windows) or terminal (Linux/OS X) and navigate to the directory where the adb executable is located using the `cd` command. On Windows: Windows Key + R > type `cmd` > press Enter. On OS X: Type `Terminal` into Spotlight and open it. Alternately, on Windows: Go to the directory where you downloaded the adb executable, Shift+Right Click and select `Open Console` (or similar) | On Linux / OS X: Right Click in the directory and select `Open Terminal here` * Type in your console window: `adb devices` to verify your device is properly connected. * If your device is selected, type in `adb logcat` to show the logcat, aka stacktrace. * Reproduce your issue on your device. * Paste the contents of your console window into a Github Gist to share on the forums or github. _Based on Stackexchange posts by Leandros and Nicolas Raoul._ #### Generating Logs via Android App Gathering log files in Android requires a third-party app that can interface with the `logcat` system. Many free apps are available via Android's "Play Store" system. You can still generate RetroArch logs from the menu. ### Generating Logs in iOS and tvOS You can generate RetroArch logs from the menu, described above. Logs by default go into the RetroArch/logs directory accessible through the Files app on iOS or the webserver on tvOS. App Store installations can opt to send crash logs to the RetroArch developers for analysis, if desired. This can be configured through the Settings app in "Privacy & Security" under "Analytics & Improvements" by turning on "Share With App Developers". ### Generating Logs with Nintendo Switch You need to have your console and your PC on the same local network. You need to have `nxlink` installed on your PC to generate logs. The devkitpro environment has it, see the [switchbrew wiki](https://switchbrew.org/wiki/Setting_up_Development_Environment) for instructions on how to install it. Run the homebrew menu on your console, and press the Y button to open the netloader prompt. Take the NRO of the core you want to launch on your PC. Open a terminal and type this command in : ``` nxlink /path/to/your/core.nro -s ``` Where `/path/to/your/core.nro` is the path to the core you want to generate logs from, on your PC. Be careful as it will overwrite any homebrew with the same name on your SD card ! That will send the homebrew and run it on your console. Logs will be shown on the terminal you ran the command from. If you want to redirect logs to the file `libnx.logs`, use this command instead : ``` nxlink /path/to/your/core.nro -s > libnx.logs 2>&1 ``` ### Generating Logs with other Nintendo Consoles At the moment there are no logging docs available for other Nintendo consoles. Please feel free to post about your situation in the libretro forums. ### Generating Logs with PlayStation Consoles At the moment there are no logging docs available for PlayStation consoles. Please feel free to post about your situation in the libretro forums. ### Generating Logs in OpenDingux (GCW-Zero and RG350) At the moment there are no logging docs available for OpenDingux. Please feel free to post about your situation in the libretro forums. ------------------------- ## Posting Logs in the Forum and Github Generally, log files are lengthy which make them difficult to read when they're pasted directly into a post on the forums or github. If your log file is more than six or seven lines long, you will be asked to post a link to it instead. One free and straightforward system for posting and sharing logs is [Github Gist](https://gist.github.com). You can paste the contents of a log file, or the log file itself, into the Gist website. After you log has been added to the Gist, press the `Create Public Gist` button to create a shareable link. ================================================ FILE: docs/guides/glui.md ================================================ # GLUI (GUI) **GLUI** (formerly known as **MaterialUI**) is RetroArch's mobile interface for smartphones. This interface is designed around touchscreen and pointer devices like a mouse/trackball. It is based on Android's "Material UI" designs. GLUI was overhauled in RetroArch 1.6.6. ![GLUI startup screen](../image/retroarch/glui/glui-main.png) ## Menu structure Content is displayed in a single column. The menus are organized into three tabs: Main Menu, Playlists, and Settings. ![GLUI thumbnails screen](../image/retroarch/glui/glui-3-tabs.png) *The three tabs of GLUI, side by side.* ### Navigating the menus GLUI is designed primarily for touchscreen use, although a gamepad can also be connected via Bluetooth or USB. Swipe left or right (or tap on the icons at the bottom of the screen) to switch between the three columns. Swipe up or down to scroll through menus. Tap on a line once to select it and enter its submenu. Tap once on the 'back arrow' icon in the top left to go back a step. Tap once on an entry in a playlist to open the quick menu, from which you can launch the content. *See [Input and Controls](input-and-controls.md)* ## Input Content is controlled using Gamepad Overlays on the device's touchscreen. A gamepad can also be connected via Bluetooth or USB. *See [Overlays](libretro-overlays.md) and [Input and Controls](input-and-controls.md)* ![GLUI gameplay with the default gamepad overlay](../image/retroarch/glui/glui-gamepad-overlay.png) *GLUI gameplay with the default gamepad overlay* ### Thumbnails By default, 2 thumbnails are displayed for each entry in a playlist. The left thumbnail is the boxart, while the right thumbnail is a gameplay screenshot. Hold on a thumbnail for 1 second then release to view the thumbnails full-screen (then tap once to close the popup). ![GLUI thumbnails screen](../image/retroarch/glui/glui-thumbnails.png) ## Themes GLUI has a range of colour schemes built in. Go to `Settings > User Interface > Appearance > Color Theme` to browse the themes and select one. GLUI does not support OS-level light/dark mode switching at this time. ![A few GLUI color schemes](../image/retroarch/glui/glui-themes3.png) ================================================ FILE: docs/guides/gui.md ================================================ # The User Interface RetroArch currently has 4 different "Menu Drivers" to choose from for its Graphical User Interface: * **[Ozone](ozone.md)**: The default skin for many host systems. * **[XMB](xmb.md)**: The "old" default skin. * **[GLUI](glui.md)**: The smartphone/touchscreen skin. * **[RGUI](rgui.md)**: The "basic" skin. The Menu Driver can be changed under `Settings> User Interface> Menu`. A restart of RetroArch will be required. ![Clockwise from top left: Ozone, XMS, GLUI, RGUI.](../image/retroarch/4_guis.jpg) *Clockwise from top: Ozone, XMB, GLUI, RGUI.* ================================================ FILE: docs/guides/import-content.md ================================================ # Importing Content !!! warning This guide assumes that you already have obtained the content legally, RetroArch does not provide users with copyrighted content. This guide uses the "scan" functionality to import your games into RetroArch's playlists sorted by console. The scan is recursive so you can organise your collection into sub-folders or potentially scan your whole computer. ## Step 1: Download database In order to have RetroArch recognise your games, you need to have a database of all the titles. !!! note Certain releases of Retroarch (e.g. Windows), come with the database files out-of-the-box. From the RetroArch main menu select "Online Updater", then choose "Update Databases". Wait for the download to finish. ## Step 2: Scan and import The "Import Content" menu can be either in the "Playlists" > "Import Content" (default), or directly accessible from the Main Menu. !!! note The location of this menu item can be toggled in "Settings" > "User Interface" > "Menu Item Visibility" > "Show 'Import Content'" and updating this from "Playlists Menu" to "Main Menu". Here you will see three options, "Scan Directory", "Scan File" and "Manual Scan". !!! note "Scan Directory" and "Scan File" are sometimes refered to as "Auto Scan". These options can only recognise content that match the database. Using the default settings, these scan options also need a coresponding core for the said content to be already added. ***1) Scan Directory:*** for importing a collection of content. Using the file browser, navigate to the folder of the content collection and select **"Scan This Directory"**. ***2) Scan File:*** for importing a single file. Navigate to file and select it. ***3) Manual Scan:*** it scans based on content file names and does not require content to match the database. Please be patient while it scans. Large collections could take several minutes. ## Step 3: Add box art This is optional. Go back to the main menu, select "Online Updater", then choose "Playlist Thumbnails Updater". Here you need to select the console you want to download. Please be patient, these take quite some time to download, especially on a slow internet connection. !!! tip In order to be able to download thumbnails for manually scanned content, the name of the playlist and the names of the entries must match the ones on the thumbnail website. ================================================ FILE: docs/guides/input-and-controls.md ================================================ # Getting started: Input and controls ## Game controllers RetroArch is intended to be easily controlled with a controller. RetroArch uses the overall term **controller** which encompasses all input hardware that could be described by the terms **joypad**, **gamepad**, **joystick**, and others. !!! info "Map controls by controller, core, or game" RetroArch allows users to configure a controller once for many cores instead of having to configure each core individually. RetroArch also provides the freedom to configure specific cores and even individual games differently if the user wants. ### What is a RetroPad? RetroArch maps real-world controller inputs to a virtual controller called a `RetroPad` . A RetroPad resembles the common modern controller layout, and has: - a D-pad - 4 face buttons with an ABXY layout like a SNES gamepad (that is: A-right, B-bottom, X-top, Y-left) - Select / Start buttons - two shoulder buttons (L1, R1) - two trigger buttons (L2, R2) - dual analog sticks like a Sony DualShock, which can also be used as a button (L3, R3). ![RetroPad Conceptual Diagram](../image/guides/retropad-conceptual-diagram.png) You don't have to map all of the RetroPad buttons to a real world button. If your real controller has less buttons than a DualShock, then the virtual RetroPad will have some unmapped buttons, that's perfectly fine. If your real controller has more buttons, the extra buttons may be used as freely configurable hotkeys. Conceptually, all RetroPad buttons can behave as analog (pressure sensitive), but the hardware typically only supports this for the trigger buttons. Gyroscope, acceleration, and illumination sensors may be supported, very much depending on the driver and the core. ### Controller autoconfiguration Most well-known controllers should work out of the box via the RetroArch autoconfiguration profile database. If the controller can be autoconfigured, the OSD will inform you of the autoconfiguration event. The menu hotkey is often pre-defined in the autoconfiguration profile. !!! info "Manual RetroPad binding" Not all controllers have autoconfigs. If that is the case for your controller, please refer to the [Manual RetroPad Binding](#manual-retropad-binding). ## Keyboard controls RetroArch provides a remappable set of bindings between a keyboard and the RetroPad abstraction as well as between a keyboard and RetroArch's hotkeys, details are [below](#default-retroarch-keyboard-bindings). ### Cores with direct keyboard input Please be aware that some cores, for example arcade emulator cores and vintage computer emulator cores, can also be configured to directly read the keyboard or controls that use a keyboard interface. **If you are using a core configured for direct keyboard access, it is recommended to use the `Game Focus` mode (default: Scroll Lock) to disable those bindings while using the keyboard device,** or unbind the conflicting RetroArch keyboard-to-RetroPad and hotkey bindings if only a few keys are needed. Otherwise, keyboard input will be captured by the RetroArch hotkeys and the core will not get the input. !!! tip Controls with keyboard interfaces can also benefit from defining a **Hotkey Enable** button. If this hotkey is defined, other hotkeys will not be activated unless it is pressed. ## Manual RetroPad binding If your gamepad is not recognized by autoconfiguration or if you would like to change its RetroPad binding, use the **Input** settings menu. ![Screenshot of input binding](../image/retroarch/xmb/autoconf.gif) - Navigate to **Settings** - Navigate to **Input** - Navigate to **RetroPad Binds** - Navigate to **Port 1 Controls** - Select **Set All Controls** - Press the buttons as required. !!! tip If you have several different controllers, do **Save Controller Profile** after each binding so that controllers will be recognized next time automatically. ## Controls for multi-player If you want to set-up local multi-player with games that support it: - Navigate to **Settings** - Navigate to **Input** - Navigate to **RetroPad Binds** Here you will find the option to set binds for multiple users. Let's set-up User 1's controller: - Navigate to **Port 1 Controls** - Select **Device Index** Select which currently plugged-in controller will be assigned to this player. After you finish, go back, select **Port 2 Controls** and repeat for user 2. In case of multiple controllers, RetroArch will assign them by default in the order they are presented by the operating system. For more customization, use the device reservation options to explicitly assign a controller to a player. ## Hotkeys Hotkeys are combinations of buttons you can press in order to access options such as saving, loading, and exiting games. Hotkey binds can be configured at `Settings` → `Input` → `Hotkeys` . If you map `Enable Hotkeys` to a button, it will require that button to be held in order to trigger any hotkeys. !!! tip To unbind (effectively, disable) a hotkey, press **Del** on your keyboard or the **Y button** (the left one of the 4 buttons) on the RetroPad. To reset a hotkey to its default, press **Space** on your keyboard or the **Start** button on the RetroPad. ## Remapping controls for individual cores or content Core Controls Remapping alters how the core receives input rather than how the gamepad is coded, for example you can tell an individual core to switch button A and B on the RetroPad for gameplay, but you can still use "A" to select in the RetroArch menu and "B" to go back. This is opposed to changing the gamepad bindings in RetroArch itself which would swap "A" and "B" in the core but would also make "B" select and "A" back in the RetroArch menu. **How to remap the controls for a single core or game:** * Start content with the core for which you want to remap controls * Go to **Quick Menu** and then **Controls** * Configure the buttons the way you want * Select **Save Core Remap File** * OR, if you want to save this remapping for the current game only, select **Save Game Remap File** ## Default RetroArch keyboard bindings ### Key bindings cheat sheet ![RetroArch standard key bindings - Commands as of 2025-05-12 superimposed on a US laptop keyboard](../image/guides/standard-key-bindings.png) Commands as of 2025-05-12 superimposed on US laptop keyboard. For most recent key bindings see the following sections. ### General controller mapping These controls are valid both in-game and in the menu: | User 1 Keyboard | Default RetroPad Mapping | Menu Action | |-----------------------------------------------------------------------------------------|--------------------------------------------------------------| ----------------------------- | | ![Up Arrow](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Arrow_Up.png) | ![RetroPad Up](../image/retropad/retro_dpad_up.png) | Move cursor up | | ![Down Arrow](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Arrow_Down.png) | ![RetroPad Down](../image/retropad/retro_dpad_down.png) | Move cursor down | | ![Left Arrow](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Arrow_Left.png) | ![RetroPad Left](../image/retropad/retro_dpad_left.png) | Move cursor left | | ![Right Arrow](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Arrow_Right.png) | ![RetroPad Right](../image/retropad/retro_dpad_right.png) | Move cursor right | | ![Q](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Q.png) | ![RetroPad L1](../image/retropad/retro_l1.png) | Scroll one page up | | ![W](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_W.png) | ![RetroPad R1](../image/retropad/retro_r1.png) | Scroll one page down | | ![Z](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Z.png) | ![RetroPad B](../image/retropad/retro_b.png) | Return to the previous screen | | ![X](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_X.png) | ![RetroPad A](../image/retropad/retro_a.png) | Select Item | | ![A](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_A.png) | ![RetroPad Y](../image/retropad/retro_y.png) | Scan content / Remove highlighted input bind | | ![S](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_S.png) | ![RetroPad X](../image/retropad/retro_x.png) | Search | | ![Shift](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Shift.png) | ![RetroPad Select](../image/retropad/retro_select.png) | Help | | ![Enter](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Enter.png) | ![RetroPad Start](../image/retropad/retro_start.png) | (see next section) | ### Menu controls While in the menu, there are additional navigation keys defined for convenience. | Keyboard Input | Retropad Input | Menu Action | | ------------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------- | | ![Backspace](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Backspace.png) | ![RetroPad B](../image/retropad/retro_b.png) | Return to the previous screen | | ![Enter](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Enter.png) | ![RetroPad A](../image/retropad/retro_a.png) | Select Item (note: Enter key is mapped to Select button in-game) | | ![Del](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Del.png) | ![RetroPad Y](../image/retropad/retro_y.png) | Scan content / Remove highlighted input bind | | ![/](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Slash.png) | ![RetroPad X](../image/retropad/retro_x.png) | Search | | ![Space](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Space.png) | ![RetroPad Start](../image/retropad/retro_start.png) | Reset to default | | | ![RetroPad L3](../image/retropad/retro_l2.png) | Scroll to previous letter | | | ![RetroPad R3](../image/retropad/retro_r2.png) | Scroll to next letter | | ![Home](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Home.png) | ![RetroPad L3](../image/retropad/retro_l3.png) | Scroll to top | | ![End](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_End.png) | ![RetroPad R3](../image/retropad/retro_r3.png) | Scroll to bottom | Analog sticks are also able to control the menu. If needed, additional hotkeys can be disabled in `Settings` → `Input` → `Menu Controls`, along with several other customization options. ### Hotkey controls Hotkey binds can be configured at `Settings` → `Input` → `Hotkeys` . If you map `Enable Hotkeys` to a key, it will require that key to be held in order to trigger any hotkeys. This can be useful in avoiding keyboard mapping conflicts between RetroArch and cores cores that use the keyboard for input. !!! Tip Hotkeys can also be mapped to controller buttons. | Keyboard Input | In-Game Action | | ------------------------------------------------------------------------------ | ---------------------------- | | ![Esc](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Esc.png) | Exit RetroArch | | ![Spacebar](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Space.png) | Fast forward toggle | | ![L](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_L.png) | Fast forward hold | | ![P](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_P.png) | Pause | | ![P](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_K.png) | Frame advance | | ![E](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_E.png) | Slow motion | | ![R](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_R.png) | Rewind | | ![H](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_H.png) | Reset | | ![F1](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_F1.png) | Menu toggle | | ![F2](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_F2.png) | Save state | | ![F3](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_F3.png) | Show FPS | | ![F4](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_F4.png) | Load state | | ![F5](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_F5.png) | Desktop menu | | ![F6](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_F6.png) | Decrease current state slot | | ![F7](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_F7.png) | Increase current state slot | | ![F8](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_F8.png) | Take screenshot | | ![F9](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_F9.png) | Mute | | ![F11](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_F11.png) | Grab mouse | | ![+](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Plus.png) | Volume Up | | ![-](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Minus.png) | Volume Down | | ![F](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_F.png) | Fullscreen toggle | | ![M](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_M.png) | Next shader | | ![N](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_N.png) | Previous shader | | ![I](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_I.png) | Netplay toggle play/spectate | | ![U](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_U.png) | Cheat toggle | | ![Y](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_Y.png) | Next cheat | | ![T](../image/Button_Pack/Keyboard_Mouse/Dark/Keyboard_Black_T.png) | Previous cheat | ## Platform-specific controls ### Nintendo Switch USB keyboards and mice: All keyboards seem to work. Not all mice seem to work. [Mouse compatibility sheet](https://docs.google.com/spreadsheets/d/1Drbo5-QuSX901MwtOytSMuqRGxeIkq2HELM806I9dj0/edit#gid=0). Touch mouse emulation: The Switch touchscreen can be used for mouse control like a laptop touchpad. The following gestures are supported. | Touch Input | Effect | |--------------------------|--------------------------------------------------------| | single finger drag | move the mouse pointer (indirectly like on a touchpad) | | single short tap | left mouse click | | dual finger short tap* | right mouse click | | dual finger drag | drag'n'drop (left mouse button is held down) | | three finger drag | drag'n'drop (right mouse button is held down) | *: hold one finger, short tap with another ================================================ FILE: docs/guides/input-controller-drivers.md ================================================ # RetroArch input and controller drivers RetroArch makes use of two input systems in order to support the full range of input devices available across RetroArch's supported platforms. - **Input Drivers** provide access to keyboards, mice, and mouse-like devices such as lightguns or touch screens. Input drivers are typically set up automatically, and are either not changeable or there is only a limited selection. - **Controller Drivers** provide access to gamepads and joysticks. On desktop platforms, controller drivers can be usually changed. The autoconfiguration profile database is different per controller driver. !!! Note Controller drivers were previously referred to as joypad drivers. Some documentation may still use the older "joypad" terminology. - **Multi-mouse** indicates if it is possible to select a separate mouse-type device (such as a lightgun) for each player. If multi-mouse is not supported, typically all pointing devices are controlling the same default cursor. - **Pointer device** indicates if it is possible for the core to query the absolute coordinates of the pointer, as opposed to the default (relative) mouse. Certain cores may only support one or the other. - **Lightgun device** indicates if it is possible for the core to query a specific lightgun device, which has a different button set compared to a RetroPad. A few platforms support physical lightguns natively, or lightguns may appear as pointer devices. - **Rumble support** indicates if the driver can pass on haptic feedback (vibration) signals. - **Autoconfig support** indicates if the driver can read the controller vendor/product identifiers and apply an automatic mapping for [RetroPad](../../guides/input-and-controls/#what-is-a-retropad). The listing below is not complete, but on the rest of the platforms, there is usually only 1 valid driver. --- ## Apple OSes **Apple Input Drivers** | Input driver | Conditions | Multi-mouse support | Pointer device | Lightgun device | |--------------|------------|---------------------|----------------|-----------------| | `cocoa` | - | No | Yes | No | **Apple Controller Drivers[^1]** | Controller driver | Conditions | Rumble support | Autoconfig support | |-------------------|------------|----------------|--------------------| | `mfi` | - | Yes | Yes | | `sdl2` | - | Yes | Yes | --- ## Linux **Linux Input Drivers** | Input driver | Conditions | Multi-mouse support | Pointer device | Lightgun device | |--------------|------------|---------------------|----------------|-----------------| | `x` | Desktop environment is X11, video driver is OpenGL (any version) or Vulkan | Yes | Yes | Yes | | `wayland` | Desktop environment is Wayland, video driver is OpenGL (any version) or Vulkan | No | Yes | Yes, button map is fixed | | `sdl` | Video driver is sdl or sdl2 | No | Yes | Yes, button map is fixed | | `udev` | No desktop environment (KMS) or X11 | Yes | Yes | Yes | | `linuxraw` | No desktop environment (KMS) | No mouse support at all | No | No | Multi-mouse support for X11 was added after RetroArch 1.20.0 and requires that RetroArch is compiled with XInput library. Use `xinput create-master` and `xinput reattach` commands to set up a second pointer and assign the physical device. **Linux Controller Drivers** | Controller driver | Conditions | Rumble support | Autoconfig support | |-------------------|------------|----------------|--------------------| | `udev` | Access to the udev interface (see below) | Yes | Yes (+[physical ID support](../../guides/controller-autoconfiguration/#physical-identifier-customization)) | | `sdl2` | - | Yes | Yes | | `linuxraw` | - | No | Yes | | `parport` | [Special adapter](../../development/retroarch/input/parallel-port-controllers/) on physical parallel port | No | No | | `hid` | Only if enabled during compilation | Yes | Yes | ### udev drivers udev is the newest input driver and uses the evdev joypad interface at `/dev/input`. It supports hotplugging and force feedback (if supported by device). udev reads evdev events directly and supports keyboard callback, mice, and touchpads. `libudev` is used to discover devices and support hotplugging. The `libudev` and `libxkbdcommon` packages are required. udev does not require X11, but udev does depend on X11 keyboard layout files being installed. ### Setting up udev permissions Most Linux distributions prevent users from capturing keyboard/mouse information by default. Only root and users in the group "input" are able to access raw input. This is a security feature in case the system is used by multiple users. The easiest way to gain access to this input is to: * **Step 1:** Add your user to the group "input" with the command: ``sudo usermod -a -G input `whoami` `` * **Step 2:** Log out, and then log back in If adding your user to the input group does not succeed, you may also set up a udev rule which makes this input accessible to non-root users: * **Step 1:** Add to `/etc/udev/rules.d/99-evdev.rules` the following text: `KERNEL=="event*", NAME="input/%k", MODE="666"` * **Step 2:** Reload the rules with `sudo udevadm control --reload-rules`. * **Step 3:** Reboot ### linuxraw drivers The linuxraw controller driver uses the legacy joystick API at `/dev/input/js*`. The linuxraw input driver requires an active TTY in order to read keyboard events. ### hid driver The hid driver on Linux platform detects Human Interface Devices via libusb. By default it is not enabled during compilation. --- ## Windows **Windows Input Drivers** | Input driver | Conditions | Multi-mouse support | Pointer device | Lightgun device | |--------------|------------|---------------------|----------------|-----------------| | `dinput` | Video driver is not sdl(2) | No | Yes | Yes | | `raw` | Video driver is not sdl(2) | Yes | Yes | Yes | | `sdl` | Video driver is sdl or sdl2 | No | Yes | Yes, button map is fixed | **Windows Controller Drivers** | Controller driver | Conditions | Rumble support | Autoconfig support | |-------------------|------------|----------------|--------------------| | `dinput` | Controller is connected as a DirectInput device | Yes | Yes | | `xinput` | Controller is connected as an XInput device | Yes | Yes | | `sdl2` | - | Yes | Yes | | `hid` | Only if enabled during compilation | Yes | Yes | ### hid driver The hid driver on Windows platform detects Human Interface Devices via libusb. By default it is not enabled during compilation. --- ## Auxiliary sensor support The libretro API provides a possibility to pass extra sensor inputs to cores: 3 axes of accelerometer/tilt sensor, 3 axes of gyroscope, and an illumination sensor. The following input drivers support extra sensors: - `linuxraw`: illumination - `sdl`: illumination (only on Linux) - `android`: accelerometer and gyroscope - `cocoa`: accelerometer and gyroscope - `vita`: accelerometer and gyroscope - `switch`: accelerometer, gyroscope and illumination - `udev`: illumination - `x`: illumination --- ## Footnotes [^1]: MFi controllers are primarily supported on Apple devices, which means that the operating systems supporting this configuration would include: - iOS: Used on iPhones and iPads. - macOS: Used on Mac computers. - tvOS: Used on Apple TV devices. ================================================ FILE: docs/guides/install-3ds2ds.md ================================================ # Downloading, Installing and Updating RetroArch for both 3DS and 2DS Family ## Prerequisites - **CFW** You must have custom firmware to run RetroArch on your 3DS or 2DS. - **Installer** You can either use `FBI installer` or `Rosalina Menu` from `Luma`. | :warning: WARNING | |:---------------------------| | Hardware or software changes on your device may damage your device. | ## Downloading and installing There are multiple ways of downloading RetroArch for your 3DS or 2DS. ### Installation You can either choose `Nightlies` or `Stable` bundle, you can find a bundle with RetroArch, all the cores and all the assets [here](https://buildbot.libretro.com/stable/{{ unit.stable }}/nintendo/3ds/), and download `RetroArch_3dsx.7z` or `RetroArch_cia.7z`. For Nightlies [here](http://buildbot.libretro.com/nightly/nintendo/3ds/) - pick the latest version(based on date), and download `...RetroArch_3dsx.7z` or `...RetroArch_cia.7z`. Just extract `RetroArch` folder to the root of your SD card `RetroArch.cia` anywhere else, to install cores use `FBI installer`. Go to the `RetroArch`folder and open the `Cores` folder. Select and install the Cores you want to use. For example; install `pcsx_rearmed_libretro.cia` for Playstation 1 Roms. #### Reduce Core and Content loading times By default, all Cores are installed in the directory `/RetroArch/Cores`. With this configuration, RetroArch Cores on 3DS take nearly 30 seconds to start, as each Core in `/RetroArch/Cores` must be initialized - including Cores which may not be needed. The same delay is experienced when loading Content (games) as well; roughly 30 seconds to finish loading. Slow MicroSD random access/transfer speeds on the 3DS may be a likely cause. To reduce loading time for Cores and Content to under 5 seconds each, complete the following steps: - **Determine Cores to be used**. These Cores will remain in the `/RetroArch/Cores` directory. - **Create directory for unused cores**. A directory name such as `/RetroArch/Cores-Notused` could be created for unused Cores. - **Move the unused Cores**. Finally, move unused Cores from `/RetroArch/Cores` to `/RetroArch/Cores-Notused` After moving unused Cores as outlined above, RetroArch Cores should start in about 5 seconds. Content should load in about 5 seconds as well. As additional Cores are needed, simply move them from `/RetroArch/Cores-Notused` to `/RetroArch/Cores`. This ensures only the required Cores are initialized by RetroArch, minimizing start times for Cores and Content. #### Additional Notes for MAME Cores MAME Content numbers in the thousands of items for MAME Cores. To help reduce loading time for MAME Content, consider creating two directories for MAME Content. This ensures frequently loaded Content is able to start faster. - **A directory for favorite MAME Content**, containing Content which will be loaded often. - **A directory for all remaining MAME Content**, containing Content which would be loaded infrequently. This approach will work fine as long as the MAME Content romset is a **Full Non-Merged romset**. If the romset is **not Full Non-Merged**, then all MAME content will need to remain in the same directory. **Full Non-Merged romsets are the simplest romset format to get started with because each romset zip contains all necessary files for one game.** For more information, please refer to [Getting started with arcade emulation](arcade-getting-started.md). ##### Control Configuration for MAME Cores Much of the Content loaded by the RetroArch MAME Cores uses a `Vertical display perspective` for the top 3DS screen, requiring the user to rotate the 3DS counter-clockwise in order to properly see the game content and access the game controls. When using Content in this configuration, the default controls won't be suitable (as the controls are typically configured for `Horizontal display perspective`). One approach to address the issue is to configure `Global Options` for controls, which would apply to the majority of games (such as `Vertical display perspective`). For games which have a different layout (`Horizontal display perspective`), the MAME menu may be used to configure a game controller configuration for that specific Content. A simple configuration example follows, in case the majority of Content uses a Vertical configuration. Load `RetroArch`, then: - **Bind a Menu hotkey** From `Main Menu` navigate to `Settings->Input->Hotkeys`. Scroll down to `Menu Toggle Gamepad Combo` or `Menu (Toggle)` and configure as desired, to display the `Menu` within Content. - **Configure Global Control for Vertical Content** From Main Menu navigate to `Settings->Input->Port 1 Controls`. Configure as desired. - **Configure In-Game Control for a piece of Horizontal Content** Load the content, then press the defined `Hotkey` to display the `Quick Menu`. Scroll down and select `Options`, then scroll down to select `Display MAME menu`; change to `ON`, then resume content. On the `MAME menu` select `Input (this game)` and adjust the settings as desired. Finally, use the previous steps to set `Display MAME menu` back to `OFF`. Controls are now set properly for the game. Following the above ensures all Content may use the proper control configuration. ================================================ FILE: docs/guides/install-android.md ================================================ # Downloading, Installing and Updating RetroArch for Android devices. ## Non-Google Play sources ### Installation via Side-loading Side-loading means installing manually downloaded APK files on Android (outside official stores).
You must follow the [installation notes](#installation-notes) for this process. #### From RetroArch.com Downloads ___ 1. Visit the retroarch.com [Downloads page](https://www.retroarch.com/?page=platforms) and select **Download Stable** or **Download Nightly**. 2. Open the downloaded APK (via a file manager if your browser does not prompt you when the download is completed). 3. Select Install. ##### From Buildbot Archives ___ All [stable](https://buildbot.libretro.com/stable/{{ unit.stable }}/android/) and [nightly](https://buildbot.libretro.com/nightly/android/) bundles are available via BuildBot If you need a specific architecture or build for testing. Builds are named with an architecture suffix: `aarch64` is a 64-bit build, `ra32` is a 32-bit build, and no suffix is a universal build that opts for 64-bit if your system supports it. > 32-bit support on Android is slowly being phased out by the industry, but these builds remain available for older devices or specific use cases. ### Installation via F-Droid ___ RetroArch's most recent stable release can be found [in the F-Droid repository](https://f-droid.org/packages/com.retroarch/) for easier automatic updating. ### (NOT RECOMMENDED) Installation via Google Play ___ RetroArch is available on the Google Play Store, but has not been updated for years due to Play Store policy changes. You may choose to use this older version, but it is not recommended. [RetroArch Plus on the Play Store](https://play.google.com/store/apps/details?id=com.retroarch.aarch64&hl=en_US "RetroArch64") (Only for 64 bit devices, additional cores) [RetroArch on the Play Store](https://play.google.com/store/apps/details?id=com.retroarch&hl=en "RetroArch") (For 32 or 64 bit devices, fewer cores) A more detailed difference between the Play Store versions can be found in [this libretro blog post](https://www.libretro.com/index.php/retroarch-android-new-versions-for-play-store-please-read/). # Installation notes ## Side-loading * Android may tell you that `the app doesn’t have permission to install APKs`. Click the available `Settings` button in that prompt. * In the next menu, turn on the toggle allowing the app install APKs. * `Hit the back button` to return to your installation. ## Allowing APK installations blocked by Google Play Protect To install RetroArch from non-Google Play sources (F-Droid, retroarch.com, etc), ensure Google Play Protect either approves it or disable the service entirely. ### Method 1: "Install anyway" in Google Play Protect ![google-play-protect_-_install-anyway-1.png](../image/guides/google-play-protect_-_install-anyway-1.png) ![google-play-protect_-_install-anyway-2.png](../image/guides/google-play-protect_-_install-anyway-2.png) * When you select “Install anyway”, Google Play Protect will ask you to authenticate your identity. For security reasons, this step cannot be captured in a screenshot, which is why it's described here instead. If Play Protect still fails to install the app even after you’ve entered the correct password, you’ll need to disable Google Play Protect. For instructions, see [Method 2: Disable Google Play Protect](#method-2-disable-google-play-protect). ### Method 2: Disable Google Play Protect If Google Play Protect still blocks the app installation even after you entered the correct password in Method 1 (a common issue on older Android versions), you'll need to temporarily disable Play Protect to proceed. Disable Google Play Protect: * Open the Play Store app first * Tap your profile icon * Select Play Protect * Tap the gear icon in settings * Toggle off "Scan apps with Play Protect" Once disabled, install the APK — Play Protect will no longer interfere with the process. ================================================ FILE: docs/guides/install-facebookportal.md ================================================ Facebook Portal is a device that allows you to have video calls with friends and family using Facebook Messenger. It has a built-in camera and microphone, and it's designed to make video chatting easier and more convenient. Now, if you want to use Facebook Portal for running RetroArch, we need to do a little tweaking. RetroArch is an emulator that allows you to play old video games on various platforms. While Facebook Portal is not specifically designed for gaming, it does have some capabilities that might make it possible. To run RetroArch on Facebook Portal, you would need to use browser. Remember that running RetroArch on Facebook Portal might not provide the best gaming experience. The device is primarily designed for video calling and might not have the same performance or compatibility as dedicated gaming devices or computers. So, while it's possible to run RetroArch on Facebook Portal, it might not be the ideal setup for gaming purposes. # Running RetroArch on Facebook Portal Portal is built on an open-source Android platform but we can't access the Google Play Store. Sure! Here's a step-by-step guide to running RetroArch on Facebook Portal: 1. Connect your controller: Start by connecting your controller to the Facebook Portal. You can do this by using via Bluetooth. Go to the settings, then Bluetooth settings. Put your controller into the Pairing mode. You will see your controller in the list. 2. Open the web browser: On the Facebook Portal, locate the web browser app. It's usually represented by an icon that looks like a globe or compass. Tap on the icon to open the web browser. 3. Visit web.libretro.com: In the web browser, enter the URL "web.libretro.com" in the address bar. This website is the official RetroArch website. 4. Select a core: On the RetroArch website, you'll find a list of cores. Choose the core that corresponds to the console you want to emulate. 5. Run the homebrews: After selecting the core, go to the "Downloads" section under the main menu. Look for the homebrews available for the console you selected. Homebrews are unofficial games or software created by independent developers. Select the file and it will load. Remember, running RetroArch on Facebook Portal might not offer the best gaming experience, as the device is primarily designed for video calling. So, manage your expectations accordingly, and have fun exploring the world of retro gaming! ================================================ FILE: docs/guides/install-genesismini.md ================================================ # Downloading and Installing RetroArch for Sega Genesis Mini - Genesis ==The installation steps or dowloading file parts of the project may differ over time.== ## Sega Genesis Mini - Genesis **Note:** You currently need the have a way to execute homebrew to run RetroArch on your Sega Genesis Mini. ## Prerequisites - FAT32 or exFat formatted USB - USB Cable(The one came with Genesis does not support data transfer, it only works for power. - *optional* OTG cable so you don't have to use second port | :warning: DISCLAIMER: | |:---------------------------| | Project Lunar made by ModMyClassic and at RetroArch/LibRetro we all love community works. We think Project Lunar is as valuable for Sega Genesis Mini. | ### Downloading and installing Project Lunar version of RetroArch is built by the ModMyClassic team. It may have a different version than RetroArch's current version. As Project Lunar is updated, the RetroArch it contains may be close to the current version. Project Page: https://modmyclassic.com/project-lunar/ #### Downloading You can download a bundle with RetroArch, all the supported cores and all the assets by going ModMyClassic's GitHub page in [here](https://github.com/Project-Lunar/Project-Lunar-Issue-Tracker/releases/tag/1.0.5). There will be few options for download, you may want to select **Zip Version** in most cases. #### Installing Extract the downloaded archive file from the zip. There will be an executable file which called **ProjectLunarUI.exe**. After running the program, choose **Install/Uninstall**. The system will warn you that it has not detected a device. When prompted, accept interactive setup support. Then follow the steps on the screen. After completing the setup, plug your USB into the second port of your device. Then click **Tools > Get RetroArch** and download the **_ALLCORES.ZIP** file from the page you went to. Thanks to this file, you will not have to download one by one. To transfer the cores, first turn off your device and remove your USB after making sure it is completely turned off. Plug in your USB to the computer and move the contents of the downloaded archive file into the **project_lunar > retroarch > cores** folder. Move your contents to **project_lunar > roms** as well. Remove your USB from your computer and insert it into the second USB port while your device is turned off, or you can plug it in from the back of the device with an OTG cable, so you can plug the controller to the second USB port. When the system is turned on, you can click on the RetroArch icon and continue. ================================================ FILE: docs/guides/install-gnu.md ================================================ --- title: Downloading, Installing and Updating RetroArch on GNU/Linux description: Instructions for setting up RetroArch on GNU/Linux systems. --- # Installing RetroArch on Linux This page contains descriptions of several officially-supported methods of installing RetroArch on systems running the GNU/Linux kernel. --- ## Flatpak (suitable for most Linux distributions) Flatpak is a distribution-agnostic packaging format with broad support throughout the Linux ecosystem. An official [RetroArch flatpak][retroarch-flatpak] is published in the Flathub repository, and can be installed in just three easy steps: ### Installation 1. Ensure that Flatpak is [enabled on your system][flatpak-setup] by opening the terminal and confirming that the following command exits with no errors: ``` shell flatpak --installations ``` 1. Confirm that the Flathub repository is configured as a [flatpak remote][flatpak-remote], so that packages from it may be installed. You can examine the flatpak remotes currently enabled on your system with this terminal command (shown with default output): ``` shell-session hl_lines="4" ra@libretro:~$ flatpak remotes --columns=name,url,homepage Name URL Homepage flathub https://dl.flathub.org/repo/ https://flathub.org/ ``` If Flathub is not among the remotes shown, this command will add it to your system: ``` shell sudo flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo ``` 1. Finally, install the RetroArch Flatpak. You have the option of making it available to only the current user, with this command: ``` shell flatpak install -y --user --from https://dl.flathub.org/repo/appstream/org.libretro.RetroArch.flatpakref ``` Or for all users with this command: ``` shell sudo flatpak install -y --from https://dl.flathub.org/repo/appstream/org.libretro.RetroArch.flatpakref ``` ### Launching the Flatpak RetroArch should now be listed in your app launcher and can also be executed from the terminal with the command: ``` shell flatpak run org.libretro.RetroArch ``` ### Updates You should keep RetroArch updated by running this command periodically from the terminal: ``` shell flatpak update -y --app org.libretro.RetroArch ``` ## Ubuntu(-based) Ubuntu provides RetroArch as a Debian [package in their official "universe" archive][ubuntu-package], which is maintained by the community with no promise of support or regular update schedule. Nevertheless, for the casual user of Ubuntu or a derivative distribution, it represents the simplest method for installing RetroArch. All that is required is to open a terminal and issue this single command: ``` shell sudo apt --upgrade --yes install retroarch ``` ### Personal Package Archives (PPAs) In an effort to improve the experience of RetroArch users on Ubuntu, official [Ubuntu flavors][ubuntu-flavors], and all of the many Linux distributions based on Ubuntu (such as Linux Mint, Zorin OS, Pop! OS, elementary OS, etc.), the Libretro Team has long been committed to producing its own Debian packages as an alternative to the ones supplied by Ubuntu in the "universe" package archive. These packages are updated much faster to keep pace with each new RetroArch version, and compiled with a greater range of features than the Ubuntu package. In addition, Debian packages are created for the vast majority of popular Libretro cores, simplifying their installation and allowing them to be updated by the system package manager on the same schedule as all other package updates. These packages are built and distributed using the [Launchpad platform][launchpad-team] operated by Canonical itself (the company which distributes Ubuntu), and split into two channels called "Personal Package Archives" (PPAs) that each cater to a specific type of user. By simply [enabling one (or both) the PPAs][help-ppas] listed below, users can seamlessly replace the Ubuntu RetroArch package on their system with those provided by the Libretro team. - [**Stable**][ppa-stable] (recommended) — includes only official releases (as announced on libretro.com / retroarch.com) - [**Testing**][ppa-testing] — builds of RetroArch and most Libretro cores from the latest source code, for test new fixes and features as soon as they're added ### Installation Follow these steps to enable the Libretro PPAs on your Ubuntu(-based) system. 1. In order to add PPAs to your system's package sources, some tools from the official package repositories are needed. Open the terminal and run this command to ensure they are installed: ``` shell sudo apt --update --yes install software-properties-common ``` 1. Just a single command is needed to add a PPA to your system's package sources. - To add the [**Stable PPA**][ppa-stable], run this command in your terminal: ``` shell sudo add-apt-repository --yes --no-update --ppa libretro/stable ``` - Or to add the [**Testing PPA**][ppa-testing], run: ``` shell sudo add-apt-repository --yes --no-update --ppa libretro/testing ``` 1. You can now install the RetroArch package from the PPAs with this command: ``` shell sudo apt --update --yes install retroarch ``` #### Verifying PPA package installation You can verify that the PPA package is installed (rather than the one from the official distribution repositories) with the `apt show retroarch` command (shown with expected output for the Testing PPA package): ``` shell-session hl_lines="14" ra@libretro:~$ apt show retroarch Package: retroarch Version: {{ unit.stable }}+r202408170734~bf25bd9149-179~ubuntu24.04.1 Priority: optional Section: games Maintainer: Libretro Team Original-Maintainer: Debian Games Team Installed-Size: 25.2 MB Provides: retroarch-dbg Depends: fonts-dejavu-core, libretro-core-info, libegl1, libgl1, […] Recommends: libgamemode0, retroarch-assets Suggests: xdg-utils Download-Size: 6,349 kB APT-Sources: https://ppa.launchpadcontent.net/libretro/testing/ubuntu […] Description: Simple frontend for the libretro library RetroArch is an open source, multi-platform frontend for the libretro API. It can be used as a modular multi-emulator system, game engine, media player and 3-D technical demonstration. These features are available through libretro cores. . It provides four built-in graphical user interface flavors: RGUI, XMB, Ozone and GLUI. Notice: There is 1 additional record. Please use the '-a' switch to see it ``` !!! tip "What to look for" Look at the **`APT-Sources:`** line in the output. If one of the PPA packages is installed, its value will begin with `https://ppa.launchpadcontent.net/libretro/`. ### Updates With this installation method, RetroArch updates will automatically be included with your system's regular package upgrades. However, you are always able to trigger an update specifically for RetroArch (if one is available) with the command: ``` shell sudo apt --update --yes upgrade retroarch ``` ## Arch Linux(-based) ### Installation #### Official package Arch Linux provides a [**`retroarch`**][arch-package] package for x86_64 systems in their official [Extra repository][arch-extra-repo]. You can install it by searching for RetroArch by name in a graphical package manager like [Octopi][octopi], or from the terminal with the command: ``` shell sudo pacman -S retroarch ``` #### Arch User Repository (AUR) package A "git" package named [**`retroarch-git`**][aur-git-package] which offers prerelease builds (similar to the Testing PPA described above) is also available in the [AUR][arch-aur]. As above, it can be installed from a package manager GUI or in the terminal using an "[AUR helper][aur-helpers]" like [`yay`][aur-yay], as in: ``` shell yay retroarch-git ``` !!! tip "Installing an AUR helper" If you wish to install the AUR package but don't yet have an AUR helper installed on your system, the following shell "one-liner" will download, compile and install `yay` for you: ``` shell pacman -S --needed git base-devel && git clone https://aur.archlinux.org/yay-bin.git && cd yay-bin && makepkg -si ``` ### Updates With this installation method, RetroArch updates will automatically be included with your system's regular package upgrades. However, you are always able to trigger an update specifically for RetroArch (if one is available) with the following commands. #### Official package ``` shell pacman -Syyuu retroarch ``` #### AUR package ``` shell yay -Syyuu retroarch-git ``` [arch-aur]: https://aur.archlinux.org/ "Arch User Repository (AUR)" [arch-extra-repo]: https://wiki.archlinux.org/title/Official_repositories#extra "Official repositories - ArchWiki" [arch-package]: https://archlinux.org/packages/extra/x86_64/retroarch/ "Arch Linux - retroarch {{ unit.stable }}-1 (x86_64)" [aur-git-package]: https://aur.archlinux.org/packages/retroarch-git "AUR (en) - retroarch-git" [aur-helpers]: https://wiki.archlinux.org/title/AUR_helpers "AUR helpers - ArchWiki" [aur-yay]: https://github.com/Jguer/yay "Jguer/yay: Yet another Yogurt - An AUR Helper written in Go (GitHub)" [flatpak-remote]: https://docs.flatpak.org/en/latest/flatpak-command-reference.html#flatpak-remotes "Flatpak Command Reference - Flatpak documentation" [flatpak-setup]: https://flatpak.org/setup/ "Flatpak—the future of application distribution" [help-ppas]: https://help.launchpad.net/Packaging/PPA/InstallingSoftware "Packaging/PPA/Installing Software - Launchpad Help" [launchpad-team]: https://launchpad.net/~libretro "Libretro in Launchpad" [octopi]: https://tintaescura.com/projects/octopi/ "Octopi - Tinta escura" [ppa-stable]: https://launchpad.net/~libretro/+archive/ubuntu/stable "Libretro Stable : “Libretro” team" [ppa-testing]: https://launchpad.net/~libretro/+archive/ubuntu/testing "Libretro Testing/Nightly : “Libretro” team" [retroarch-flatpak]: https://flathub.org/apps/org.libretro.RetroArch "Install RetroArch on Linux | Flathub" [ubuntu-flavors]: https://ubuntu.com/desktop/flavours "Ubuntu flavours | Ubuntu" [ubuntu-package]: https://packages.ubuntu.com/search?keywords=retroarch&searchon=names "Ubuntu – Package Search Results -- retroarch" ================================================ FILE: docs/guides/install-ios.md ================================================ # Downloading, Installing and Running RetroArch on iOS ## Installation ### App Store As of May 15th 2024, RetroArch is available on the App Store worldwide. App Store : https://apps.apple.com/us/app/retroarch/id6499539433 ### Sideloading You can still sideload the app onto your devices if you want. There are 4 ways of sideloading: - Jailbreaking, not something covered here - Build RetroArch from source using Xcode, as described [here](../development/retroarch/compilation/ios.md) - Using a third party tool such as [AltStore](https://altstore.io/) that can install a built application by performing many of the same actions Xcode performs. - Use Xcode with a developer account to load the IPA file directly, employing a signing tool like [iOS App Signer](https://www.iosappsigner.com/) !!! Warning RetroArch or Libretro is not affiliated with AltStore or iOS App Signer in any way. You can also use alternative applications that can perform this function. #### App Store vs Sideloading There are very few differences between the App Store and sideload builds. Installing via the App Store is easier, and sideload builds expire and need to be refreshed; for these reasons it is preferable to use the App Store version, and new users should start with that. However, there are a few reasons you may prefer to sideload: - Additional cores. We only include cores we maintain in-house or whose upstream teams have given us explicit approval to distribute it via marketplaces. This includes most but not all cores. - Dynamic Recompilation (a.k.a. dynarec or JIT). This will speed up some cores (e.g. ppsspp) and enable other cores (e.g. flycast). #### Downloading Download one of the following IPA files depending on your needs: | | | | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | iOS 12+ | [Stable](https://buildbot.libretro.com/stable/{{ unit.stable }}/apple/ios-arm64/RetroArch.ipa) | [Nightly](https://buildbot.libretro.com/nightly/apple/ios-arm64/RetroArch.ipa) | | iOS 9+ (reduced feature set; may not work on newer devices) | [Stable](https://buildbot.libretro.com/stable/{{ unit.stable }}/apple/ios9/RetroArchiOS9.ipa) | [Nightly](https://buildbot.libretro.com/nightly/apple/ios9/RetroArchiOS9.ipa) | | tvOS 13+ | [Stable](https://buildbot.libretro.com/stable/{{ unit.stable }}/apple/tvos-arm64/RetroArchTV.ipa) | [Nightly](https://buildbot.libretro.com/nightly/apple/tvos-arm64/RetroArchTV.ipa) | Most people should start with the Stable build. The Nightly build contains the latest commits available on GitHub, and the latest enhancements and features that are added daily. The Nightly build may not be as stable as the Stable version. It is possible to build RetroArch for older versions of iOS, though due to resource constraints these are not provided. See the [instructions for building iOS](../development/retroarch/compilation/ios.md) to build it yourself. #### Installation for non-Jailbreak devices In order to install the RetroArch on your non-Jailbreak device, we need to use a third-party application. You cannot add or update cores after installation as they are signed executables and can only be updated by updating and resigning the entire application. The IPA files linked above contain [all of the available iOS/tvOS cores](https://buildbot.libretro.com/nightly/apple/ios/latest/). ##### iOS App Signer 1. Download and launch iOS App Signer, and add the downloaded `.ipa` file. 2. Use an existing Apple Development certificate or sign up for a free or paid developer account. 3. Ensure your device is registered. Refer to [link](https://developer.apple.com/help/account/register-devices/register-a-single-device) for details. 4. Create a provisioning profile for your device. Follow these [instructions](https://developer.apple.com/help/account/manage-profiles/create-a-development-provisioning-profile). 5. Use reverse-domain formatting, e.g., `com.myname.retroArch` (replace 'myname' with your name). 6. Click start and save the new `.ipa` file. 7. Open Xcode, go to `Window -> Devices and Simulators`, and select your device. 8. In the right pane under 'INSTALLED APPS,' either drag and drop the new `.ipa` file or click '+' to navigate to the file. ##### AltStore 1. Install and launch AltServer. 1. Hold Option (macOS) or Left Shift (Windows) when clicking the AltServer icon to reveal new "Sideload .ipa…" menu option 1. Select the device you want to install RetroArch on (must be on the same Wi-Fi network as AltServer) 1. Enter the email and password for your Apple ID ## Using RetroArch On an iPhone, you'll be presented with the "GLUI" touch interface; in versions after 1.19.1 on iPad the default switched to the "Ozone" interface. If you have an mFi controller, you can control both interfaces that way as well. On the Apple TV, you'll be shown the "Ozone" interface. You need to use an mFi controller with an Apple TV. The Siri Remote only functions as an LRUD interface; it will not work as a controller. When you first start RetroArch, you'll notice that you're missing images. You'll want to run the Online Updater: - From the main menu, choose "Online Updater" - Choose: - Update Core Info Files - Update Assets - Update Databases - Update Overlays - Update GLSL Shaders ### Adding Content #### iOS The easiest way to add content into RetroArch's sandbox is through the Apple Files app. Run RetroArch first and it will create several folders. After running RetroArch, open the Files app, and in Browse -> On My iPhone, you should now see a RetroArch folder. You can place your content in any directory or subdirectory in that folder (including creating your own subdirectories). You can use the Files app to copy the content from iCloud to the folder on your phone. Additionally, in the `Load Content` menu, selecting `Open...` will open the system file chooser screen, and from there you can select files to copy. Copied files go into the `downloads` folder by default. #### tvOS RetroArch on tvOS has a built-in webserver. While RetroArch is running, open a browser on your computer and open the URL that RetroArch displays. You can use the web-based UI to create subdirectories and upload or download files. You can place your content in any directory or subdirectory in that folder (including creating your own subdirectories). Additionally, on versions newer than 1.19.1, there is a built-in WebDAV server that listens on port 8080. You can connect to it using Finder on macOS by choosing "Connect to Server..." in the "Go" menu (**⌘-K**) and entering `http://appletv.local:8080`, replacing "appletv.local" with the name of your AppleTV or its IP address. !!! Warning tvOS does not provide apps with a persistent storage area; instead it allows for up to 500kb meant for configuration data. The disk space shown through the web UI is a cache space. If the OS needs to reclaim disk space, it will delete files from that cache space without warning. This includes state and saves! When this happens, you will immediately see that the appearance of RetroArch is wrong, as the assets will need to be re-downloaded. ### JIT Several cores are improved by enabling JIT, while others will not work at all without it. The only way to enable JIT is to convince the OS that RetroArch is being debugged. One way of doing this is to build with Xcode, launch the app from Xcode with the debugger attached, and leave Xcode running. Another way is to use AltServer to enable JIT on RetroArch after it has been opened (but before a core has been loaded). Note: JIT is not enabled on the App Store version of RetroArch. Apple doesn't allow apps to run with JIT. Some core will not function as intended. ================================================ FILE: docs/guides/install-lakka.md ================================================ # Downloading, Installing and Updating Lakka for PC. ## What is it? ___ Lakka is the official Linux distribution of RetroArch and the libretro ecosystem. Each game system is implemented as a libretro core, while the frontend RetroArch takes care of inputs and display. This clear separation ensures modularity and centralized configuration. Lakka is a lightweight Linux distribution that transforms a small computer into a full blown retrogaming console. | :warning: DISCLAIMER | |:---------------------------| | Lakka is still under heavy development. In its current state, the project allows you to play most games on most platforms. However, expect bugs, missing features or features not working as intended, and hardware that is yet to be supported. If you find a bug, you can declare it in our [tracker](https://github.com/libretro/Lakka-LibreELEC/issues), unless already reported. | ## Prerequisites - **SD card or USB** You need a USB or SD Card to write the installation image. - **Flashing Software** You can use either `Etcher` or `Win32 disk imager`. ## Download Lakka ___ Click here to get the [64bit](http://le.builds.lakka.tv/Generic.x86_64/Lakka-Generic.x86_64-2.2.2.img.gz) version or click here to get the [32bit](http://le.builds.lakka.tv/Generic.i386/Lakka-Generic.i386-2.2.2.img.gz) version. Please note that due to the wide variety of PC hardware, Lakka may not work on your hardware. Those image are USB images, not CD or DVD images, those installation mediums are unsupported. Also, we don't support virtualization and dualboot. Lakka is meant to be installed on real hardware. ### Flashing Lakka Image The following softwares are fine however you can use any other software you want. The following softwares are not related to RetroArch or Libretro in any way. You must act consciously when providing or using these softwares. #### Etcher Etcher is a free and open-source utility used for burning image files such as .iso and .img files, as well as zipped folders to create live SD cards and USB flash drives. • Run **Etcher** • Select `Lakka Image` • Select USB drive • Click **Flash** #### Win32 Disk Imager This program is designed to write a raw disk image to a removable device or backup a removable device to a raw image file. • Click on the **folder icon** • Select the **image file** • Select drive letter **UNDER DEVICE** • Click **Write** ## Installation Lakka is still under heavy development. In its current state, the project allows you to play most games on most platforms. However, expect bugs, missing features or features not working as intended, and hardware that is yet to be supported. ___ ### The Live USB Mode Lakka can be installed on an USB key, and be booted in Live Mode on any PC that supports Lakka’s requirements. This Live Mode is persistent: all changes will be saved to the key, safely storing games within the USB. **Unknown Sources** To avoid compromising the safety of your device, always use applications provided through our official channels. 1. Insert your USB drive into your computer. 2. Boot from USB. 1. You can use Boot Device Options by pressing the key specified by your motherboard manufacturer. 2. You can choose to boot from USB in the BIOS. *The above options may vary depending on your motherboard model.* 3. Wait during the `bootloader phase`. This will start the Lakka operating system via USB. This Live Mode is persistent: all changes will be saved to the key, safely storing games within the USB. You will be able to check if Lakka works on your hardware, without altering your PC’s hard drive or partitions. Certain settings and configurations may not be saved in spite of the persistence property. ### Full Setup Installing Lakka on your device is as simple as installing any other operating systems. You may experience unexpected errors during setup. Lakka is still under construction. 1. Insert your USB drive into your computer. 2. Boot from USB. 1. You can use Boot Device Options by pressing the key specified by your motherboard manufacturer. 2. You can choose to boot from USB in the BIOS. *The above options may vary depending on your motherboard model.* 3. Type `installer` or `live` 4. Select **Install Lakka**. 5. Use the **up/down** arrows to select the drive to install. *Observe the warnings on the screen. If you continue the targeted drive will be wiped out.* 6. Select Yes in confirmation alerts. 7. After the installation, you will return to the Main menu. **Remove the USB** and **select Reboot**. Your computer will launch Lakka on the next Boot. ## Conclusion ___ Lakka is still under heavy development. In its current state, the project allows you to play most games on most platforms. More information can be found in the [Lakka documents](http://www.lakka.tv/doc/Home/). You may also want to check the [Official Forum](https://forums.libretro.com/c/libretro/lakka-tv-general). ================================================ FILE: docs/guides/install-libnx.md ================================================ # Downloading, Installing and Updating RetroArch for Switch | :warning: WARNING | |:---------------------------| | You need to have Atmosphère custom firmware to run RetroArch on your Switch. Hardware or software changes on your device may damage your device. | ## Prerequisites Neither RetroArch nor LibRetro support or recommend that your device run CFW. - Atmosphère [^1] - FAT32 formatted SD card ## Downloading and installing There are multiple ways of downloading RetroArch for your Switch. ### Using the stable bundle (recommended) You can find a bundle with RetroArch, all the cores and all the assets [here](https://buildbot.libretro.com/stable/{{ unit.stable }}/nintendo/switch/libnx/RetroArch.7z). Just extract the archive to the root of your SD card to install or update your copy of RetroArch (overwrite any existing file). ### Using the nightlies and/or the online updater (advanced users) If you don't want to download all cores at once, you can go [here](https://buildbot.libretro.com/nightly/nintendo/switch/libnx/latest/) and only pick the ones you want. Put the downloaded NROs in `retroarch/cores` on your SD card. You can run them directly using the homebrew menu. Alternatively, you can download only one core and use the Online Updater inside of RetroArch to download or update additional cores later. ## Running RetroArch using title takeover The preferred way of running RetroArch is to use Atmosphère's title takeover feature. This allows you to (temporarily) replace a game with the homebrew loader, which will then be used to load RetroArch. Make sure to use the latest version of Atmosphère before continuing. | :warning: WARNING | |:---------------------------| | You need at least one title on the console (whether it's a digitally puchased game or a demo or a cartridge game or even an homebrew NSP). If you can pick an up to date game that's better as you won't be nagged everytime you run it. | Atmosphère now contains everything needed to run homebrews out of the box. To do so, simply run any game while holding the R key. Make sure to hold the key until you can actually see the homebrew menu. Select RetroArch in the list to start! If you wish to change the key, you can edit `/atmosphere/loader.ini` and change `override_key` here. You can add a `!` in front of the key to flip the condition ("run homebrew if the key is pressed" versus "run homebrew if the key isn't pressed"). ## Updating Updating RetroArch is the same as installing it, download a higher or lower version (in this case, downgrade) than the version you have and overwrite existing files. ## Glossary ### "Atmosphère" Atmosphère is a work-in-progress customized firmware for the Nintendo Switch. ### "NRO" An NRO file is an executable file used by the Nintendo Switch. It contains compiled code for an application or game. NRO files may also store assets for Homebrew Launcher, such as a icon and metadata. [^1]: https://github.com/Atmosphere-NX/Atmosphere ================================================ FILE: docs/guides/install-ludo.md ================================================ # Downloading, Installing and Updating Ludo for PC. ## What is it? ___ Ludo is an Emulator Frontend able to run retro video games. Ludo does not emulate the consoles itself, but does it through emulator plugins called libretro cores. Libretro cores are well known emulators (like Snes9x or Genesis Plus GX or PCSX) stripped from their user interface. They contain only console specific logic. | :warning: DISCLAIMER | |:---------------------------| | Ludo is still under heavy development. In its current state, the project allows you to play most games on most platforms. However, expect bugs, missing features or features not working as intended, and hardware that is yet to be supported. If you find a bug, you can declare it in our [tracker](https://github.com/libretro/ludo/issues), unless already reported. | ## Prerequisites - GLFW 3.3 - OpenGL >= 2.1 - OpenAL ## Download Ludo ___ Click here to get the [latest](https://github.com/libretro/ludo/releases/latest) version. Please note that due to early development phase, Ludo _may_ not work on your OS as expected. In most scenarios, Ludo works as intended. ## Ludo [Ludo](http://ludo.libretro.com/) is a minimalist frontend for emulators. [Ludo is part of LibRetro](https://github.com/libretro/ludo). Separating the frontend from the emulation logic has the following advantages: - Frontend developers only have to code the user interface once - Developing a new frontend functionality can benefit all the emulators at once - Emulator developers can benefit from a mature user interface without coding it - Gamers can configure emulators all at once - The user interface, configuration, and storage are consistent across emulators From the gamer perspective, Ludo is a universal retro game browser and player. It offers a gaming experience optimized for TV and gamepads, but can also be used on a traditional PC with a keyboard. Currently, Ludo can run on the following platforms: - Windows 64-bit (Tested on Windows 10) - Max OS X 64-bit - Linux 64-bit - Linux on Raspberry Pi 32-bit There is also an Operating System version of Ludo called LudOS. It looks and behaves exactly the same, but can be burnt to a USB drive or an SD card to recreate a video games console experience. You can setup LudOS on a dedicated TV box to enjoy gaming from your couch. You can also boot it off USB on any laptop in a perfectly portable way. ### Features Ludo's User Interface has the following functionalities: - Gamepad driven: everything can be done through the gamepad instead of the mouse - TV optimized: looks nice on a wide screen - Controller auto configuration when plugged - Automatic configuration of literally everything - Game collection scanner for generating playlists with thumbnails - Video filters through simple shaders - Taking game screenshots - Saving/Loading game state anytime, organized by date with screenshots - Emulator specific settings - Soft-patching .ips and .ups ### Focus on playing Ludo's user interface is distraction free and configuration is always optional. ![Nes Tab](../image/guides/ludo/tabnes.png) Scan your games and browse your collection categorized by system with playlists showing in-game screenshots. ![Playlist](../image/guides/ludo/playlist.png) A contextual menu gives you access to actions and quick save / quick load anytime. ![Quick Menu](../image/guides/ludo/quickmenu.png) We chose the best emulators for the job, configured with sane defaults guaranteeing a balance of speed and accuracy. ![Quick Menu](../image/guides/ludo/ingame.png) ### Ludo as an Operating System Ludo also exists in the form of an Operating System called LudOS. It behaves and looks exactly the same and can be installed directly on a TV Box to recreate a game console experience. - [PC 64bit](https://github.com/libretro/LudOS/releases/download/v1.0-alpha30/LudOS-Generic.x86_64-1.0-alpha30.img.gz) - [Raspberry Pi 2/3](https://github.com/libretro/LudOS/releases/download/v1.0-alpha30/LudOS-RPi2.arm-1.0-alpha30.img.gz) - [Raspberry Pi 4](https://github.com/libretro/LudOS/releases/download/v1.0-alpha30/LudOS-RPi4.arm-1.0-alpha30.img.gz) The OS version of Ludo, LudOS, adds these OS centric functionalities: - Flash-able using Etcher - Auto expanded filesystem on first boot - Connecting to Wi-Fi networks, with a virtual keyboard - Robust monolithic updates for the OS - Adding games through Windows Share protocol or SSH - Controlling services like SSH, Samba, Bluetooth ___ ## Frequently Asked Questions You may have a lot of questions or ideas about Ludo, some of which we tried to answer below. Apart from that, you can also ask your questions via [Discord](https://ra-link.web.app/discord). ### How is Ludo different from RetroArch? Ludo will stay smaller than RetroArch by only implementing the core features and by targeting less platforms. By not adding advanced functionalities we aim to deliver a stable frontend for beginner users on Windows, Mac OSX and Linux. Some design choices are different, for example we support less cores, and choose cores for the user. The cores are packaged in the frontend so no additional step is required to launch a game. ### How is Ludo similar to RetroArch? As RetroArch, Ludo is a libretro frontend, so the way of communicating with the emulators is the same. Same cores, similar UI patterns, gamepad driven UI, same game thumbnails, mostly the same game database, same terminology. I think we can also say same developers, as I am an important contributor of the libretro team, and all the people who provided me with help are also member of the libretro community. It definitely shares the same values. ### Why not implementing Ludo as a menu driver in RetroArch? To keep a software stable on a number of different platforms, it is important to keep a small codebase with a good test coverage. It is also important to not introduce changes at a high rate. RetroArch is an extremely active project and has a growing codebase that makes it harder to reach stability. Also, RetroArch is a very powerful and sophisticated frontend, and one of the common criticism is that it exposes too many configuration options for the average retro gamer. Implementing Ludo as a menu driver of RetroArch would solve none of these issues. ### Does Ludo offer a better scanning method compared to RetroArch? No, the scanner logic is basically the same and Ludo supports even less ROM formats. CDs are scanned based on file name instead of serial number. Ludo's scanner faster for this reason and because it leverages goroutines. ### Can you add feature X to Ludo? The answer is likely to be no, as we're trying to keep the code small, only bugfixes are really welcome. We encourage you to fork Ludo and add the feature yourself. It should be fairly easy given the scope of the project. If you are able to author a very useful improvement with a minimum of changes we might merge your change. ### Emulated consoles Ludo includes the following libretro cores (emulators): bluemsx fbneo fceumm gambatte genesis_plus_gx handy mednafen_ngp mednafen_pce_fast mednafen_psx mednafen_saturn mednafen_supergrafx mednafen_vb mednafen_wswan mgba np2kai o2em pcsx_rearmed picodrive pokemini prosystem snes9x stella vecx virtualjaguar Ludo can run games from these consoles: Atari 5200, Atari 7800, Atari Jaguar, Atari Lynx, GCE Vectrex, MSX, MSX2, Various Arcade Games, Game Boy, Sega SG-1000, Sega Game Gear, Sega Master System, Sega Genesis / Mega Drive, Sega 32X, Sega CD, Sega Saturn, Nintendo NES, Super Nintendo / Super Famicom, Nintendo Virtual Boy, Nintendo Game Boy, Nintendo Game Boy Advance, NEC PC Engine, NEC PC Engine CD, NEC PC-98, NEC PC-FX, Sharp X68000, Sony PlayStation, 3DO ## Conclusion ___ Ludo is still under heavy development. In its current state, the project allows you to play most games on most platforms. More information can be found in the [Ludo documents](https://github.com/libretro/ludo/wiki). ================================================ FILE: docs/guides/install-macos.md ================================================ # Downloading, Installing and Updating RetroArch for macOS ## Downloading and installing Download one of the .dmg files from here: * [Stable](https://buildbot.libretro.com/stable/{{ unit.stable }}/apple/osx/universal/RetroArch_Metal.dmg) * [Nightly](https://buildbot.libretro.com/nightly/apple/osx/universal/RetroArch_Metal.dmg) The install follows the standard process of opening the .dmg file and copying RetroArch.app into the Applications folder. ### About the "Metal" build name The downloadable builds are named "Metal" for historical reasons. This build is a Universal binary (supporting both Intel and Apple Silicon Macs) and includes multiple video drivers: Vulkan, glcore (OpenGL 3/4), and an experimental Metal driver. Most users should use the Vulkan or glcore video drivers. !!! warning "Metal video driver is experimental" The metal video driver within RetroArch is experimental, largely untested, and not well supported. If you encounter issues, switch to the Vulkan or glcore video driver instead. The Metal build requires macOS 10.13 or later. It is possible to build RetroArch for older versions of macOS, though due to resource constraints these are not provided. See the [instructions for building on macOS](../development/retroarch/compilation/osx.md) to build it yourself. ### Stable vs nightly builds Most people should start with the Stable build. The Nightly build contains the latest commits available on GitHub, and the latest enhancements and features that are added daily. The Nightly build may not be as stable as the Stable version. ## Updating There are no automatic updates in RetroArch. When updating, simply download and open the new .dmg file, and copy RetroArch.app into Applications. When prompted, choose to overwrite the old version. ================================================ FILE: docs/guides/install-ps2.md ================================================ # Downloading and Installing RetroArch for PlayStation 2 | :warning: DISCLAIMER | |:---------------------------| | You currently need the have a way to execute homebrew to run RetroArch on your PlayStation 2. | ## Prerequisites This is probably the most straightforward way to install RetroArch. - FreeMCBoot ## Downloading and installing ### Downloading !!! info Nightly files will give you the latest developments. This is sometimes dangerous and sometimes innovative. We will use the Stable version and recommend it. You can download a bundle with **Stable** version of RetroArch, all the supported cores and all the assets by clicking [here](http://buildbot.libretro.com/stable/{{ unit.stable }}/playstation/ps2/RetroArch_elf.7z). You can download **Nightly** version of RetroArch by clicking [here](http://buildbot.libretro.com/nightly/playstation/ps2/RetroArch_elf.7z). ### Installing Installation is also very simple. Just create `RetroArch` folder where put all the cores (.elf). Copy this folder into a USB stick. Finally, use your favorite file explorer (usually `UlaunchELF`) to navigate to `mass0:\`, then enter in `RetroArch` folder and launch the core you wish. ================================================ FILE: docs/guides/install-ps3.md ================================================ # Downloading and Installing RetroArch for PlayStation 3 | :warning: DISCLAIMER | |:---------------------------| | You need to have any-CFW(Rebug, Ferrox etc.) custom firmware to run RetroArch on your PlayStation 3. Hardware or software changes on your device may damage your device. | ## Prerequisites This is probably the most straightforward way to install RetroArch. - FAT32 formatted USB, It should be partitioned as MBR rather than GPT. - any-CFW ## Downloading and installing There are multiple ways of downloading RetroArch for your Playstation 3. ### Download the correct file There are two types of CFW files. One of them is `CEX` and the other is `DEX`. CFW devices with `CEX` systems are more specific to the end user. On the other hand the `DEX` version is more for developers. You can use RetroArch in two ways and benefit from the same features. Always check which version of your CFW you have and download the correct file. You can find a bundle with RetroArch, all the cores and all the assets for `CEX` and `DEX` by clicking [here](https://www.retroarch.com/index.php?page=platforms) and scroll down to the PlayStation 3 section. ## Installing Installation is also very simple. Just extract the archive to the root of your USB. Put your USB to right USB port. Use the CFW package installer to select and install RetroArch's pkg file. You can watch the short video Demonstration by clicking on the image below. ================================================ FILE: docs/guides/install-psc.md ================================================ # Downloading and Installing RetroArch for PlayStation Classic ==You currently need the have a way to execute homebrew to run RetroArch on your PlayStation Classic.== ## Prerequisites - FAT32 or exFat formatted USB2.0(some USB 3.0 are working as well) - USB needs to be renamed as "SONY" | :warning: DISCLAIMER | |:---------------------------| | Project Eris made by ModMyClassic and RetroBoot made by u/genderbent, at RetroArch/LibRetro we all love community works. We think Project Eris and RetroBoot is as valuable for PlayStation Classic. | | :warning: DISCLAIMER | |:---------------------------| | The installation steps or dowloading file parts of the project may differ over time. | ## Downloading and installing Project Eris version of RetroArch is built by the ModMyClassic team. It may have a different version than RetroArch's current version. As Project Eris is updated, the RetroArch it contains may be close to the current version. ### Downloading These two versions may contain different contents from each other. While the main purpose of Project Eris may be the Ultimate PlayStation Classic, RetroBoot runs RetroArch directly. #### Project Eris You can download a bundle with RetroArch, all the supported cores and all the assets by going ModMyClassic website in [here](https://modmyclassic.com/project-eris/). There will be few options for download, you may want to select **Full Package** in most cases. #### RetroBoot You can find more details at u/genderbent's post down below. https://www.reddit.com/r/PlaystationClassic/comments/g8ht0y/release_retroboot_11_the_lightweight_alternative/?utm_source=reddit&utm_medium=usertext&utm_name=PlaystationClassic&utm_content=t3_fd652s ### Installing Installation may sound complicated but it's not. Format your USB to `exFat` or `FAT32` and rename as `SONY`. Transfer all files in Package to USB. Make sure your device fully power-off, **you should remove power cable**, then plug your USB to second port or use OTG cable then plug into power socket. Plug back power cable, you will see **Power** led will turn *Amber* then press power button. Follow on screen instruction if you use Project Eris, RetroBoot will boot directly RetroArch. ================================================ FILE: docs/guides/install-psp.md ================================================ # Downloading and Installing RetroArch for PlayStation Portable ==You currently need to have a custom firmware called PRO-C to run RetroArch on your PlayStation Portable. Hardware or software changes on your device may damage your device. PRO-C must be running before running RetroArch, if you run RetroArch before running PRO-C, the device will say the executable is corrupted..== ## Prerequisites - Pro CFW(latest version)[^1] ## Downloading, Installing and Updating ### Downloading You can download a bundle with the **Stable** version of RetroArch, all the supported cores and all the assets by clicking [here](http://buildbot.libretro.com/stable/{{ unit.stable }}/playstation/psp/RetroArch.7z). You can download the **Nightly** version of RetroArch with all the same extras by clicking [here](https://buildbot.libretro.com/nightly/playstation/psp/RetroArch.7z). !!! info Nightly builds will give you the latest development changes. This is sometimes unstable! We will use the Stable version for this guide. ### Installing Installation is also very simple. Just create a `RetroArch` folder under `PSP/Game` directory on your Memory Stick and transfer the archive files to the `PSP/Game/RetroArch` folder, then go to `Memory Stick™` under **Game** press **X**, and then select RetroArch. Press **X** again to open. ### Updating Download the latest version and extract it into 'PSP/Game/RetroArch' on the Memory Stick. Accept when prompted to overwrite. [^1]: https://code.google.com/archive/p/procfw/downloads ================================================ FILE: docs/guides/install-psv.md ================================================ # Downloading and Installing RetroArch for PlayStation Vita ==You need to have custom firmware(HENkaku) to run RetroArch on your PlayStation Vita. Hardware or software changes on your device may damage your device.== ## Prerequisites This is probably the most straightforward way to install RetroArch. - HENkaku (latest version)[^1] - VitaShell[^2] ## Downloading and Installing We're gonna download two files to get the full experience. One of these files is the `.vpk` version of RetroArch and the other is the `data` package with assets. **RetroArch.vpk** by itself does not have any important assets. Thus, it is lighter than other versions. We will need the data file for the assets. ### Downloading !!! info inline end A Piglet/ShaccCg Wrapper Library for OpenGL ES 2.0 Support on the Vita. RetroArch Piglet is still WIP and not finished however you can try it but you will need [PIB-Configuration-Tool](https://github.com/SonicMastr/PIB-Configuration-Tool). You can download a stable RetroArch by clicking [here](http://buildbot.libretro.com/stable/{{ unit.stable }}/playstation/vita/RetroArch.vpk). If you want to install the Nightly version, you can also use [this link](http://buildbot.libretro.com/nightly/playstation/vita/RetroArch.vpk). Nightly files will give you the latest developments. This is sometimes dangerous and sometimes innovative. We will use the Stable version and recommend it. You can download `RetroArch's data` file from [this link](http://buildbot.libretro.com/stable/{{ unit.stable }}/playstation/vita/RetroArch_data.7z) or [nightly](http://buildbot.libretro.com/nightly/playstation/vita/RetroArch_data.7z). !!! info Nightly files will give you the latest developments. This is sometimes dangerous and sometimes innovative. We will use the Stable version and recommend it. ### Installing Connect your PS Vita with your PC via _VitaShell_. Move your `RetroArch.vpk` to root of your sdcard. Disconnect PS Vita from your PC. Enter the `ux0:` directory, you will see a lot of files, scroll down to the bottom until you see `RetroArch.vpk`. Press your action key, it can be _O_ or _X_. You may receive a warning asking for the reliability of the file you downloaded, if you downloaded this file from our channels, you can accept and continue. Once the installation is complete, run the **RetroArch** once and you will see that Fonts and Images are missing. Close `RetroArch` and connect PS Vita to PC with `VitaShell`. Once you have made the connection, move the files of the downloaded `data.7z` archive to `ux0:/data/retroarch/`. After successful file transfers, close the application and run RetroArch again. !!! info If you want higher resolution you could use Sharpscale[^3] plugin. [^1]: https://github.com/henkaku [^2]: https://github.com/TheOfficialFloW/VitaShell [^3]: https://github.com/cuevavirus/Sharpscale ================================================ FILE: docs/guides/install-steamlink.md ================================================ # Downloading and Installing RetroArch for Steam Link ==Steam Link build isn't in automated build due both SteamLink SDK and LibRetro changes. However you can download [here](https://github.com/fpscan/RetroArch-AppImage/releases/tag/steam) for decent version. The download and installation process is as follows, and may change in the future. Threads, alsa, pulse, neon and shaderpipeline are disabled, RGUI theme is pre-configured and most Cores installed into the root folder for full efficiency.== ## Prerequisites This is probably the most straightforward way to install RetroArch. - FAT32 formatted USB ## Download You can find a cores bundle with RetroArch by clicking [here](https://www.retroarch.com/index.php?page=platforms) and scroll down until you see the **Steam Link** section. ## Getting USB Ready ### Setting up RetroArch Getting RetroArch ready to install is very simple. Create the file structure in the root directory of your USB as follows: > steamlink/apps/ Unzip the `RetroArch.zip`, move the `RetroArch` folder into the `apps` folder we just created. ## Content Management Transferring files to Steam Link can be a bit tedious. You can put your contents inside the `Content` folder in the `RetroArch` folder, however our goal is to make this process more sustainable. In this case SSH or USBmount will help us. ### SSH In order to use an SFTP connection with SSH, we must first enable SSH. It's easy to enable SSH on your Steam Link. To do this, go to `steamlink` folder and create two nested folders first create the `Config` directory then enter it and create the `System` directory there. The directory structure should be as follows; > steamlink/config/system/ Then, enter the `System` directory and create an empty text file named `enable_ssh.txt`. Within this, create a blank text file, and label it **enable_ssh.txt**. The final directory structure should be as follows: > steamlink/config/system/enable_ssh.txt > ### USBmount USBmount is an alternative way to connect `/mnt/disk`. You can find more detailed information in the link below. [https://steamcommunity.com/app/353380/discussions/1/152393186490496699/](https://steamcommunity.com/app/353380/discussions/1/152393186490496699/) Put your USBmount folder into `steamlink/apps/` *RetroArch is not affiliated with the above link this link may change in the future or may not be original, this subject may vary.* ## Installation After completing the above operations, you should have a directory structure like the one below. Repeat the above steps until you reach the final result. | | | | | | |---|---|---|---|---| | steamlink | apps | retroarch |... | | | | config | system | enable_ssh.txt | | Format your USB to FAT32 type for fresh install. Move the `steamlink` folder we just created into your USB root. Unplug your USB and make sure your SteamLink is completely turned off by unplugging the power cord. Plug your USB into the first USB port, and then plug in the power cable. When Steam Link boots, RetroArch structure will be read, and RetroArch will be installed. Remove the USB after you see the RetroArch logo on the home screen. You can run the application by pressing the RetroArch logo. ## Content Transfer We can transfer our content with SSH or USBmount we have previously configured. ### SSH Find out the IP address that SteamLink receives, which you can learn from your router or SteamLink network settings. Create an SFTP connection with your trusted FTP tool. SteamLink SSH username is `root` and password is `steamlink123`, 21 for FTP and 22 for SFTPthe sample scenario for this is as follows. It may be different(ip address) in your case. RetroArch is not related to the specified applications and cannot be held responsible. FileZilla | Host | Username | Passoword | Port | |---|---|---|---| | 192.168.1.5 | root | steamlink123 | 22 | Go to root folder and open `apps` folder, you will see RetroArch folder in there. Open it and move your contents to `contents` folder. ### USBmount Install USBmount the same way we install RetroArch. Remove the `RetroArch` folder from the `apps` directory before installation. Otherwise it will re-install on every boot. After completing the installation, create a folder on your USB and move your contents. Then plug the USB into your SteamLink and run the installed `USBmount` application. ================================================ FILE: docs/guides/install-windows-2000-me-98SE.md ================================================ # Downloading, Installing and Updating RetroArch for Windows 2000 / ME / 98SE operating systems. ==You must have `WinRAR 4.11 (32-bit)` in order to unzip `RetroArch.7z` in Windows 2000.== ## Downloading and installing There are multiple ways of downloading RetroArch for your Windows 2000 / ME / 98SE operating systems. `Installer` or `Download` in [here](https://www.retroarch.com/index.php?page=platforms) both options provide you with the lastest RetroArch, the only difference is that one is a self extracting installer, and the other one an archive you have to extract manually. ## Downloading You can either choose `Nightlies` or `Stable` bundle, you can find a bundle with RetroArch, all the cores and all the assets [here](https://buildbot.libretro.com/stable/{{ unit.stable }}/windows-msvc2005/x86/), and download `RetroArch.7z` or `RetroArch-MSVC05-Win32-setup.exe`. For Nightlies [here](http://buildbot.libretro.com/nightly/windows-msvc2005/x86/) - pick the latest version(based on date), and download `...RetroArch.7z` or `RetroArch-...-msvc2005-x86-setup.exe`. !!! info You can download `RetroArch_cores.7z` file to download only Core files. ## Installing If you pick the 7z archive package, extract it in a folder that doesn't require administrator permissions such as C:\Users\yourusername\RetroArch. Don't extract it to Program Files or your Windows folder. If you pick the executable file, double click exe file and follow the instructions on-screen to install... ================================================ FILE: docs/guides/install-windows.md ================================================ # Downloading, Installing and Updating RetroArch for Windows 7 and Later ## Downloading First decide if you want a stable release or a nightly. Both options provide you with the latest RetroArch, the only difference is that one is a self extracting installer, and the other one an archive you have to extract manually. Both are portable installation which means the RetroArch setup is: - It's self-contained - It doesn't need users to guess random locations for configurations files - It's easy to update by just replacing files ### Stable The stable version is our first priority and the main distribution version. Since it is the major release, it comes out periodically. Stable releases take more time to manufacture, but new features become available in the next version. For example: A version can have a new theme and feature, and in the next version, this theme and feature can be removed, improved or changed. As can be understood from the name of Stable, this version is more stable because it is controlled accordingly to make it work better on the platform it is suitable for. Stable release are [here](https://buildbot.libretro.com/stable/{{ unit.stable }}/windows/), and then select the architecture of your computer. ### Nightly This version contains the latest commits available on GitHub, and the latest enhancements and features are added daily. This version may not be as stable as Stable version because it is built daily, but this does not mean that it is not stable. The current nightly is [here](https://buildbot.libretro.com/nightly/windows/). There are several files you can download in these folders. For a new installation you want **RetroArch.7z** or the setup package (**RetroArch-20XX-XX-XX-setup.exe**). ## Installing If you pick the 7z archive package, extract it in a folder that doesn't require administrator permissions such as *C:\Users\yourusername\RetroArch* or any other drive. Don't extract it to *Program Files* or your Windows folder. This could case some issues. ## Updating You can update the installation by downloading the latest **20XX-XX-XX-RetroArch.7z** package and overwriting the executable. If you pick the installer package we recommend to use the default location, follow the installation steps and you should be good to go. You can update the installer version by downloading the latest version and re-running the installer. | :warning: WARNING | |:---------------------------| | If you were running a stable release prior to 1.4.0. you will need to update the system libraries. You can do so by downloading the full **RetroArch.7z** package or **redist.7z** from the download locations. | ## Starting RetroArch On the first run you will be greeted by this screen: ![Screenshot](../image/retroarch/ozone/first_run.webp) From here you can launch content, change settings and build up your content collection. ### Keyboard Controls The RetroArch user interface is designed with gamepad navigation in mind but it also features robust keyboard and mouse support. Learn more about keyboard input at [Input and Controls](input-and-controls.md). ### Gamepad Controls XINPUT controllers should work out of the box. If the controller can be autoconfigured the OSD will inform you of the autoconfiguration event. We also include autoconf profiles for many popular controllers. If your controller doesn't auto configure you can follow this procedure: ![Screenshot](../image/retroarch/xmb/autoconf.gif) - Navigate to **Settings** - Navigate to **Input** - Navigate to **Input User 1 Binds** - Select **User 1 Bind All** - Press the buttons as required | :warning: TIP | |:---------------------------| | If you have several different controller types you may want to use the **User 1 Save Autoconfig** followed by **User 1 Bind Default All** options after binding in order to achieve hotplug functionality | ### Directory Configuration Configuring directories is an important aspect to get the best RetroArch experience possible. To configure the directories follow these steps: - Navigate to **Settings** - Navigate to **Directory** - Select the directory you want to changed - Navigate to the desired location You should always configure the following paths: - System Directory for *system files* - Savefile Directory for *save files* - Savestate Directory *save state files* - Browser Directory for *your content* | :warning: TIP | |:---------------------------| | The **Browser Directory** is used as a startup location which allows easy access to your content library. | ### Installing Cores RetroArch requires cores to run any content. You can download cores directly from RetroArch's interface by following this procedure: ![Core updater](../image/retroarch/ozone/core_downloader.gif) - Navigate to **Online Updater** - Navigate to **Select Core Downloader** - Select the core you want to download ### Running Content After you have installed one or more cores you can run your content following this procedure: - Navigate to **Load Content** - Browse to the folder that contains the content you want to run - Select the content that you want to run - If you have more than one compatible core you will be asked to select the core you want to use for that purpose ![Run content](../image/retroarch/ozone/run_content.gif) | :warning: TIP | |:---------------------------| | By default loading content will trigger a content scan. If your content matches with any of our databases it will be added to a playlist for easy access. You can find the playlists by navigating to the right of the main menu. Every content you launch is added to a history playlist that you can use to load it again quickly at any time | ## Glossary Here is the list of terms in a LibRetro, RetroArch or platform subject, field, or area of usage, with accompanying definitions. `frontend` : A frontend is a program designed to run libretro cores such as Kodi's RetroPlayer, RetroArch, Phoenix, Minir `core` : A core is a program that has been ported to the libretro API and runs inside a libretro frontend `content` : Content can be a game, an image, a video, an audio file that is executed by a core. In most cases contents are the ROMs of an emulated platform `retropad` : RetroPad is libretro’s input abstraction controller, it’s the interface between the physical controller and the core inputs `save files` : Save files are saves that are made from within a game, usually cross platform and should work across emulators in most cases `save states` : Save states are snapshots of the content memory at a particular moment, these are not always cross platform and most certainly won’t work on a different emulator than the one used to create them `system files` : Additional files that might or not be part of the romset that might be needed to get some content to work (usually referred to by the BIOS term) `autoconf` : A configuration file that has button definitions for a particular gamepad ================================================ FILE: docs/guides/kms-mode.md ================================================ ## Purpose KMS (Kernel Mode Setting) mode is a feature where RetroArch can use the OpenGL or Vulkan driver outside Xorg/Wayland, running straight in the virtual terminal. It is a fairly obscure feature, but very powerful in a console scenario. ## Requirements To use KMS mode you need: - MESA version 9.0+ (including dev package) - Use of Vulkan requires KHR_Display extension, present from Mesa 21 onwards - libgbm 9.0+, libdrm (including dev package) - Open source driver which supports KMS - ./configure with flags "--enable-kms" and "--enable-egl" After compiling RetroArch, you should see this when running `retroarch --features`: KMS: KMS/EGL context support: yes If KMS mode is working correctly, RetroArch should start up without any desktop environment as well, straight from the terminal. ================================================ FILE: docs/guides/latency.md ================================================ # Latency RetroArch is capable of next-frame responsive time. This means that there should be no nearly no perceivable difference in terms of input latency from real hardware, FPGA/clone or original hardware. On top of all that, there are various settings you can configure to optimize the results even more. ## Next-frame response time indistinguishable from real hardware RetroArch is truly in a league of its own when it comes to input responsiveness, and it keeps confounding even us here at Libretro. Several independent researchers did their own research on RetroArch's latency and came away being quite blown away by the results, completely shattering several long-held myths that up until now had been accepted as gospel in emulation circles: The hierarchy for loading is: * That emulation will always have an implicit 3 to 5 frames of input lag, and that therefore FPGA-based hardware will always hold a distinct advantage over software-based emulation. * That there's nothing one can do to avoid this RetroArch shatters these myths. It has been demonstrated by independent researchers that a next-frame response time (≤16ms!) achievable with RetroArch! This means zero frames of input lag is achievable, indistinguishable from real hardware. Whoever told you that input lag was a given with emulators and that you needed FPGA in order to avoid this latency, should get him/herself acquainted with RetroArch. Post-RetroArch, latency indistinguishable from real hardware is perfectly possible! Check out people's findings here on our forum and participate, don't just take our word for it! Link [here](https://forums.libretro.com/t/an-input-lag-investigation/4407/534). "With Pitfall, I witnessed a response on the very next frame. In the video shown to the left, you can clearly see me hit the button near the end of one frame, and on the next, Harry jumps! Essentially no way to improve compared to original hardware. Pack it up. We’re done here" "Ever since I tried Retroarch for the first time there was no doubt in my mind that it was the future. It overcame the crippling input lag that plagues many stand alone emulators." "[With RetroArch], it is possible to get to the same input lag as the original hardware, which may be as little as whatever is left of the current frame. At 60fps (16ms) this could be anywhere from 0ms to 16ms, which averages out to about 8ms. There is no room for improvement above that as far as the software is concerned." ## Configurable latency mitigation tools RetroArch provides you with all the tools you need to combat latency in your games. This includes options such as: * Frame Delay * Synchronization Fences (GPU Hard Sync) * Video drivers for new graphics technology APIs like Vulkan, which can drive latency down even further. * Maximum amount of configurable swap chains. * Can be set from 1 to 3 depending on your video driver, your GPU, and the video context driver that is being used by RetroArch. * Vulkan supports this feature natively, but video drivers might not implement setting lower max swapchains. * You can choose between different audio drivers which can have an effect on overall perceived latency * Windows: You can choose between WASAPI (available since Windows 7), XAudio (available since Windows XP), and DirectSound. * Linux: Depending on the build, you can choose between ALSA, PulseAudio, OSS, and audio servers like JACK. * Adjustable audio buffering for lower/higher audio latency * Adjustable audio resampler quality * Several video context drivers to choose from * Linux: Some video driver contexts like DRM/KMS on Linux allow for granular swapchain control, which should allow for an even better gameplay experience. It also allows you to boot RetroArch without an active X Server running (assuming your video driver supports this). * Wayland is supported on Linux. This is an advanced display server that is being increasingly pushed as a replacement for X11. Note that whether or not you can use this depends on your video driver. * Ability to turn off window compositing for better latency results (NOTE: This is only possible on Windows 7, Microsoft disallows this on Windows 8 and later) * Configurable swap interval ================================================ FILE: docs/guides/launch-content.md ================================================ # Launching Content !!! warning This guide assumes that you already have obtained the content legally, RetroArch does not provide users with copyright content. You should already have both cores and content, now we just have to launch it! ### Launching Go back to the Main Menu and select **Load content**. From the last guide you should have already set the default start directory, if this is the case choose **Start directory**. If you haven't set it or you are choosing other content (such as downloaded content) select the relevant option. From here it is up to you to navigate your game folder and find the game you want to try, select it once you have. !!! note If the game is zipped you will be presented with two options. *Browse archive* will allow you to open it and select the contents. While *Load archive* will try and load the archive as an image. In most cases if you simply just compressed the image, either option will do. !!! note RetroArch will automatically choose the appropriate core for your content based on file extension. However if two or more cores use the same file extension, it will ask you to choose the core. You should always choose the platform the game was suppose to run on. ### Playing Well done, you have finally launched your first game with RetroArch. If you setup your controller take note of the RetroPad concept. With this you will not have to setup a controller for each console, instead the RetroPad will adapt depending on what console your playing. To return to RetroArch, press F1 or the RetroArch button on mobile. This will bring up the menu where you can change core settings, or otherwise configure the current content, or close it. !!! warning On PC's pressing *Esc* twice will close RetroArch without saving. ================================================ FILE: docs/guides/led-drivers.md ================================================ # LED drivers for RetroArch Libretro cores can have extra on/off outputs, that provide simple visual feedback such as illuminated Start buttons for arcade or disk activity happening inside the emulated system. Available LED drivers: * `overlay` - control individual elements of a RetroArch overlay * `rpi` - control physical LEDs connected to GPIO pins * `keyboard` - control keyboard state LEDs * `sysled` - control built-in LEDs under Linux ## Configuration In case of all drivers, the LED driver type and the individual LED mapping needs to be added to `retroarch.cfg`. At present, this is not possible via the RetroArch menu system, the configuration file needs to be edited directly. Note: first LED is referred as `led1_map` in configuration file, but indexing starts from 0 on core side. There is no common mapping of LEDs for cores, but some of them use first LED for indicating power status, and second for disk drive activity. ## Overlay driver For overlay driver to have effect, make sure to activate a compatible overlay. The driver will set the visibility of `overlay0_desc0_overlay`, `overlay0_desc1_overlay` etc. items according to the input from the core. #### Example: overlay driver with 2 LEDs led_driver = "overlay" led1_map = "0" led2_map = "1" ## RPi driver The RPi driver will set the specified GPIO pins to `out` direction and then set the value via filesystem entry `/sys/class/gpio/gpio%d/value`. This entry is present typically on Raspberry Pi single board computers. #### Example: RPi driver with first LED assigned for GPIO pin 18 led_driver = "rpi" led1_map = "18" ## Keyboard driver The keyboard driver will utilize the keyboard Num Lock (0), Caps Lock (1), and Scroll Lock (2) LEDs. It works under Windows, and X11 (since RetroArch 1.9.1). Note: this driver does not work under Linux Wayland or KMS mode, and in case of X11, access to Num Lock and Caps Lock may be limited, check [this answer]( https://unix.stackexchange.com/questions/179286/change-the-status-of-the-keyboard-leds-from-within-an-x-session-without-root-a). #### Example: keyboard driver with second LED assigned for Scroll Lock, while leaving first LED explicitly unassigned. led_driver = "keyboard" led1_map = "-1" led2_map = "2" ## Sysled driver The sysled driver will set the brightness of supported mainboard LEDs via filesystem entry `/sys/class/leds/led%d/brightness`. This entry is present typically on Raspberry Pi single board computers, where led0 is the green LED usually indicating MMC card activity, and led1 is the red LED. Note that these filesystem entries may be writable by root only, enable access with e.g. `sudo chmod a+w /sys/class/leds/led*/trigger /sys/class/leds/led*/brightness` before running RetroArch. This driver was added in RetroArch 1.15.0. #### Example: sysled driver with first led output from core assigned to led1, second to led0 led_driver = "sysled" led1_map = "1" led2_map = "0" ================================================ FILE: docs/guides/libretro-overlays.md ================================================ # What is a Libretro Overlay? Imagine a libretro core playing a game or video on your screen. Now imagine attaching a clear piece of glass over your screen that you can draw on, attach touchscreen buttons to, or use to display an image of a vintage CRT television in your old bedroom. That layer of glass would be the **overlay** -- a virtual 'layer' between you and the video signal. ### What's the difference between an Overlay and a Bezel? With Libretro, **bezels** are one subtype of **overlay**. If you have experience with game emulators, you may be familiar with the term Bezel, which describes images that wrap around the emulated screen. Often this is to display an image of the original arcade cabinet or game console being emulated. [dan2hos demonstrated this bezel-style overlay for Sonic 2 in the libretro forums](https://forums.libretro.com/t/libretro-classic-tv-overlay-border/3820: ![Bezel overlay](../image/guides/overlay-customaspectexample.jpg "Bezel-style overlay example with Sonic 2"); ### What's the difference between an Overlay and a Shader? Shaders manipulate the video image being displayed by the Libretro core, so often the two are used in tandem. For example, you might want to use **shaders** to manipulate a Sega Genesis emulator core's video output to look just like a vintage Trinitron CRT television. Then you might use an **overlay** to wrap an image of that exact television around the emulated video. Another way that **shaders** and **overlays** are used together is to 1) use a **shader** to enhance dithered or low resolution images from a handheld emulator core as they are displayed on a modern HD smartphone and then 2) use an **overlay** to add touchscreen buttons to that emulator. # Overlay Touchscreen Functionality Overlay touch functionality allows users to create an input interface that is mouse or touch oriented regardless of whether the original system or libretro core was built for these forms of input. The overlay images are displayed with transparency over the regular game image, and the user is able to trigger input by pressing on designated parts of the overlay. Overlays are built from a collection of images and a text configuration file which makes it straightforward to change both the look and functionality of this overlay. Learn more about this aspect of Libretro's Overlay tech over in the Overlay Spec. An example of a touchscreen overlay, demonstrated with the Dinothawr core: ![Dinothawr overlay example](https://wiki.libretro.com/images/5/5c/Retroarch-dinothawr-overlay.jpg "Dinothawr overlay example") # Activating an Overlay via the GUI Overlays require at least one image (`.png`) and a configuration file (`.cfg`) in order to activate them. **Notes:** - The configuration file should have the exact same name as the first image file (the only image file if your overlay only has one image). - Do not use spaces in the filename. - These files should be placed together in the libretro `overlay` folder. In order to activate an overlay, go to the RetroArch `Settings` menu. Find the `Onscreen Display` submenu. From this menu you can activate the Overlay system and select which overlay file to display. # Setting Up Per-Core Overlays in RetroArch ## Per-Core Overlays via the RetroArch GUI 1. Go to the `Settings` menu and find the `User Interface` submenu and enable `Show Advanced Settings` 2. Go to the `Settings` menu and find the `Configuration` submenu. Make sure that `Use Content-Specific Core Options If Available` and `Load Override Files Automatically` are enabled. 3. Set up the Overlay according to your preferences. 3. Load a game. Open the RA "Quick Menu" and then use the GUI to set up the Overlay according to your preferences. 4. From the Quick Menu, select `Save Core Overrides`. ## Per-Core Overlays via RetroArch CFG Files To be written # Setting Up Per-Game Overlays in Retroarch ## Per-Game Overlays via the RetroArch GUI 1. Go to the `Settings` menu and find the `User Interface` submenu and enable `Show Advanced Settings` 2. Go to the `Settings` menu and find the `Configuration` submenu. Make sure that `Use Content-Specific Core Options If Available` and `Load Override Files Automatically` are enabled. 3. Load a game. Open the RA "Quick Menu" and then use the GUI to set up the Overlay according to your preferences. 4. From the Quick Menu, select `Save Game Overrides`. ## Per-Game Overlays via RetroArch CFG Files The first time you set up a per-game overlay: 1. Ensure that these two options are set in retroarch.cfg: `game_specific_options = "true"` and `auto_overrides_enable = "true"` 2. The first time you load content with these settings, RetroArch will create a settings override directory structure and a `.opts` configuration file which you can use as a template to correctly name and locate your overlay configuration files. 3. If the automatically-generated file is named `Dinothawr.opts`, you would name your per-game override `Dinothawr.cfg`. 3. The new RetroArch `.cfg` should only include the options you want to change for this single game. #### Overlay options that can be changed include: - `input_overlay` - Path to the correct overlay - `input_overlay_enable` - `input_overlay_opacity` - `input_overlay_scale` - `input_overlay_enable_autopreferred` - `input_overlay_show_physical_inputs` - `input_overlay_hide_in_menu` **Note:** You can change more than just the overlay by specific any content-specific options -- for example you might also decide to set `video_shader_enable = "true"` and `video_shader = "/usr/share/libretro/shaders/classic-crt-television.slang"`, etc. # Where can one find Overlays to use? - Interactive overlays are managed within: https://github.com/libretro/common-overlays - Decorative border overlays are managed within: https://github.com/libretro/overlay-borders # More about Overlays - Visit the official [Libretro Overlays Forum](https://forums.libretro.com/c/retroarch-additions/retroarch-overlays) ================================================ FILE: docs/guides/memorymonitoring.md ================================================ # Memory Monitoring in libretro There are many reasons someone might want to peek into the memory contents of a core to see what is happening at a given memory address at a given time. The most common use is for awarding achievements, like those from [RetroAchievements](retroachievements.md), but it can also be used for speedrunning/streaming assistant programs, machine learning applications, and more. Cores that support memory monitoring can typically fetch and award [RetroAchievements](retroachievements.md), but if a core is not specifically mentioned on the [RetroAchievements](retroachievements.md) team's [official list of supported cores](https://docs.retroachievements.org/general/emulator-support-and-issues.html), there may be issues with some achievement-awarding logic not functioning properly or other unexpected behavior. Unsupported cores may be excluded from [RetroAchievements](retroachievements.md)' "hardcore" mode and leaderboards, as well. If you need to use an unsupported core to interact with [RetroAchievements](retroachievements.md) for whatever reason (e.g., on platforms where no officially supported core is available), please do not bother them with tickets or manual unlock requests, which will be closed without investigation. They are offering a free service through volunteer labor, and we should respect their time. To be clear: the cores listed on this page support libretro's memory monitoring functionality but may or may not be supported by the [RetroAchievements](retroachievements.md) team. Please consult their [official list of supported cores](https://docs.retroachievements.org/general/emulator-support-and-issues.html) before requesting support from them. ## **Cores Compatibility** ### Arcade (various manufacturers) #### Arcade | Core | Supported | Notes | |----------------------------------------------------|:---------:|:------| | [FinalBurn Neo](https://github.com/libretro/FBNeo) | ✔ | AES bios is required for many Neo Geo achievements. AES Asia (neo-epo.bin) is generally English. | | [MAME](https://github.com/libretro/mame) | ✕ | Support is not likely to ever be possible. The same is true for all MAME variants. | ### Apple #### Apple II | Core | Supported | Notes | |-------------------------------------------------|:---------:|:------| | [AppleWin](https://github.com/audetto/AppleWin) | ✕ | | #### Arduboy | Core | Supported | Notes | |-------------------------------------------------|:---------:|:------| | [Arduous](https://github.com/Arduboy/Arduboy) | ✔ | RetroArch 1.10.2 or higher required | ### Atari #### Lynx | Core | Supported | Notes | |--------------------------------------------------|:---------:|:------| | [Gearlynx](https://github.com/drhelius/Gearlynx) | ✔ | | #### 2600 | Core | Supported | Notes | |----------------------------------------------------------------|:---------:|:------| | [Stella](https://github.com/libretro/stella-libretro) | ✔ | | | [Stella 2014](https://github.com/libretro/stella2014-libretro) | ✕ | | #### 7800 | Core | Supported | Notes | |-------------------------------------------------------------|:---------:|:------| | [ProSystem](https://github.com/libretro/prosystem-libretro) | ✔ | | #### Jaguar | Core | Supported | Notes | |----------------------------------------------------------------------|:---------:|:------| | [Virtual Jaguar](https://github.com/libretro/virtualjaguar-libretro) | ✔ | Due to vast core issues, support of this system is extremely limited. | #### Lynx | Core | Supported | Notes | |------------------------------------------------------------------|:---------:|:------| | [Beetle Lynx](https://github.com/libretro/beetle-lynx-libretro) | ✔ | | | [Handy](https://github.com/libretro/libretro-handy) | ✔ | | | [Holani](https://github.com/LLeny/holani-retro) | ✔ | | ### Bandai #### Wonderswan / Wonderswan Color | Core | Supported | Notes | |-------------------------------------------------------------------|:---------:|:------| | [Beetle Cygne](https://github.com/libretro/beetle-wswan-libretro) | ✔ | | ### Coleco #### ColecoVision | Core | Supported | Notes | |---------------------------------------------------------|:---------:|:------| | [blueMSX](https://github.com/libretro/blueMSX-libretro) | ✔ | | | [FinalBurn Neo](https://github.com/libretro/FBNeo) | ✕ | | | [Gearcoleco](https://github.com/drhelius/Gearcoleco) | ✔ | | | [JollyCV](https://github.com/libretro/jollycv) | ✔ | | | [SMS Plus GX](https://github.com/libretro/smsplus-gx) | ✕ | | ### GCE #### Vectrex | Core | Supported | Notes | |---------------------------------------------------|:---------:|:------| | [vecx](https://github.com/libretro/libretro-vecx) | ✔ | | ### Magnavox #### Odyssey 2 | Core | Supported | Notes | |---------------------------------------------------|:---------:|:------| | [o2em](https://github.com/libretro/libretro-o2em) | ✔ | | ### Mattel #### Intellivision | Core | Supported | Notes | |--------------------------------------------------|:---------:|:------| | [FreeIntV](https://github.com/libretro/FreeIntv) | ✔ | Controls involve an on-screen overlay that may not be easy to use for all games. | ### Microsoft #### MSX / MSX2 | Core | Supported | Notes | |---------------------------------------------------------|:---------:|:------| | [blueMSX](https://github.com/libretro/blueMSX-libretro) | ✔ | | | [fMSX](https://github.com/libretro/fmsx-libretro) | ✕ | Some games may require mapper adjustment in core options to run. | | [FinalBurn Neo](https://github.com/libretro/FBNeo) | ✕ | MSX2 is not supported. | ### NEC #### PC Engine - TurboGrafx-16 / PC Engine CD - TurboGrafx-CD | Core | Supported | Notes | |-----------------------------------------------------------------------------|:---------:|:------| | [Beetle PCE FAST](https://github.com/libretro/beetle-pce-fast-libretro) | ✔ | Highest speed. Does not support SuperGrafx games. | | [Beetle SuperGrafx](https://github.com/libretro/beetle-supergrafx-libretro) | ✔ | High speed. Supports SuperGrafx games. | | [Beetle PCE](https://github.com/libretro/beetle-pce-libretro) | ✕ | | | [Geargrafx](https://github.com/drhelius/Geargrafx) | ✔ | | | [FinalBurn Neo](https://github.com/libretro/FBNeo) | ✕ | | #### PC-FX | Core | Supported | Notes | |------------------------------------------------------------------|:---------:|:------| | [Beetle PC-FX](https://github.com/libretro/beetle-pcfx-libretro) | ✔ | | #### PC-8000 / PC-8800 | Core | Supported | Notes | |---------------------------------------------------------|:---------:|:------| | [QUASI88](https://github.com/libretro/quasi88-libretro) | ✕ | | ### Nintendo #### Nintendo DS | Core | Supported | Notes | |---------------------------------------------------------|:---------:|:------| | [MelonDS 2021](https://github.com/libretro/melonDS) | ✔ | External BIOS recommended, but no longer required. RetroArch 1.9.14 nightly or newer required for hashing to work. DSi mode currently is not supported for achievements. | | [MelonDS DS](https://github.com/JesseTG/melonds-ds) | ✔ | Achievements supported for DS and DSi mode. | | [DeSmuME](https://github.com/libretro/desmume) | ✔ | External BIOS recommended, needs to be enabled in core options | | [DeSmuME 2015](https://github.com/libretro/desmume2015) | ✔ | | #### Game Boy / Game Boy Color | Core | Supported | Notes | |-----------------------------------------------------------|:---------:|:------| | [Gambatte](https://github.com/libretro/gambatte-libretro) | ✔ | Preferred core. | | [SameBoy](https://github.com/libretro/SameBoy) | ✕ | | | [Gearboy](https://github.com/drhelius/Gearboy) | ✔ | | | [mGBA](https://github.com/libretro/mgba) | ✔ | Robust feature set. Currently the only core with GB Camera support. | | [VBA-M](https://github.com/libretro/vbam-libretro) | ✔ | Currently the only core with gyro support via analog sticks | | [Mesen-S](https://github.com/SourMesen/Mesen-S) | ✕ | | | [Emux GB](https://github.com/libretro/emux) | ✕ | | | [TGB Dual](https://github.com/libretro/tgbdual-libretro) | ✕ | | | [bsnes](https://github.com/libretro/bsnes-libretro) | ✕ | SGB only | | [bsnes-hd](https://github.com/DerKoun/bsnes-hd) | ✕ | SGB only | | [higan Accuracy](https://gitlab.com/higan/higan) | ✕ | SGB only, [Achievement support isn't going to be added](https://forums.libretro.com/t/is-higan-105-accuracy-supposed-to-be-slow-on-a-3-ghz-ivy-bridge-i7/13405/7?u=esoptron) | | [nSide Balanced](https://github.com/libretro/nSide) | ✕ | SGB only, [Achievement support isn't going to be added](https://forums.libretro.com/t/is-higan-105-accuracy-supposed-to-be-slow-on-a-3-ghz-ivy-bridge-i7/13405/7?u=esoptron) | #### Game Boy Advance | Core | Supported | Notes | |---------------------------------------------------------------|:---------:|:------| | [mGBA](https://github.com/libretro/mgba) | ✔ | | | [VBA-M](https://github.com/libretro/vbam-libretro) | ✔ | | | [VBA Next](https://github.com/libretro/vba-next) | ✔ | | | [gpSP](https://github.com/libretro/gpsp) | ✕ | Very high speed, but has not been thoroughly tested with achievements. A few games will fail to start or crash frequently. Please prefer other cores when device performance allows. | | [Beetle GBA](https://github.com/libretro/beetle-gba-libretro) | ✔ | Experimental core, should not be used without good reason. | | [Meteor](https://github.com/libretro/meteor-libretro) | ✕ | | #### NES | Core | Supported | Notes | |-------------------------------------------------------|:---------:|:------| | [Mesen](https://github.com/SourMesen/Mesen) | ✔ | Supports FDS, very high accuracy, relatively high performance cost | | [FCEUmm](https://github.com/libretro/libretro-fceumm) | ✔ | Supports FDS | | [QuickNES](https://github.com/libretro/QuickNES_Core) | ✔ | | | [Nestopia](https://github.com/libretro/nestopia) | ✕ | [**Achievements are not fully supported yet**](https://github.com/libretro/docs/pull/10) | | [bnes](https://github.com/libretro/bnes-libretro) | ✕ | | | [Emux NES](https://github.com/libretro/emux) | ✕ | | | [FinalBurn Neo](https://github.com/libretro/FBNeo) | ✕ | | #### Nintendo 64 | Core | Supported | Notes | |----------------------------------------------------------------------|:---------:|:------| | [Mupen64Plus-Next](https://github.com/libretro/mupen64plus-libretro) | ✔ | Preferred core. Supports greater graphic customization and upscaling. | | [ParaLLEl N64](https://github.com/libretro/parallel-n64) | ✔ | Supports 64DD games. Can play -some- hacks reliant on low accuracy via alternate plugins. | #### Pokemon Mini | Core | Supported | Notes | |--------------------------------------------------|:---------:|:------| | [PokeMini](https://github.com/libretro/PokeMini) | ✔ | | #### SNES | Core | Supported | Notes | |------------------------------------------------------------------------------|:---------:|:------| | [Snes9x](https://github.com/libretro/snes9x) | ✔ | Preferred core. High speed, moderate accuracy. Actively maintained. | | [Snes9x 2010](https://github.com/libretro/snes9x2010) | ✕ | Has many issues with achievements, unlikely to ever be supported. | | [Snes9x 2005 Plus](https://github.com/libretro/snes9x2005) | ✕ | | | [Snes9x 2005](https://github.com/libretro/snes9x2005) | ✕ | | | [Snes9x 2002](https://github.com/libretro/snes9x2002) | ✕ | | | [Mesen-S](https://github.com/SourMesen/Mesen-S) | ✔ | High accuracy, high performance cost. | | [Beetle Supafaust](https://github.com/libretro/supafaust) | ✕ | Only SRAM is exposed currently. | | [Beetle bsnes](https://github.com/libretro/beetle-bsnes-libretro) | ✕ | | | [bsnes](https://github.com/libretro/bsnes-libretro) | ✕ | | | [bsnes-hd](https://github.com/DerKoun/bsnes-hd) | ✕ | | | [bsnes-mercury Accuracy](https://github.com/libretro/bsnes-mercury) | ✕ | [SRAM is not exposed currently](https://github.com/libretro/bsnes-mercury/issues/88) | | [bsnes-mercury Balanced](https://github.com/libretro/bsnes-mercury) | ✕ | [SRAM is not exposed currently](https://github.com/libretro/bsnes-mercury/issues/88) | | [bsnes-mercury Performance](https://github.com/libretro/bsnes-mercury) | ✕ | [SRAM is not exposed currently](https://github.com/libretro/bsnes-mercury/issues/88) | | [bsnes 2014 Accuracy](https://github.com/libretro/bsnes-libretro) | ✕ | | | [bsnes 2014 Balanced](https://github.com/libretro/bsnes-libretro) | ✕ | | | [bsnes 2014 Performance](https://github.com/libretro/bsnes-libretro) | ✕ | | | [bsnes C++98 (v085)](https://github.com/libretro/bsnes-libretro-cplusplus98) | ✕ | Has some color rendering issues | | [higan Accuracy](https://gitlab.com/higan/higan) | ✕ | [Achievement support isn't going to be added](https://forums.libretro.com/t/is-higan-105-accuracy-supposed-to-be-slow-on-a-3-ghz-ivy-bridge-i7/13405/7?u=esoptron) | | [nSide Balanced](https://github.com/libretro/nSide) | ✕ | [Achievement support isn't going to be added](https://forums.libretro.com/t/is-higan-105-accuracy-supposed-to-be-slow-on-a-3-ghz-ivy-bridge-i7/13405/7?u=esoptron) | #### Virtual Boy | Core | Supported | Notes | |-------------------------------------------------------------|:---------:|:------| | [Beetle VB](https://github.com/libretro/beetle-vb-libretro) | ✔ | | ### RPG Maker | Core | Supported | Notes | |------------------------------------------------|:---------:|:------| | [EasyRPG](https://github.com/libretro/easyrpg-libretro) | ✕ | | | [mkxp-z](https://github.com/mkxp-z/mkxp-z) | ✔ | Only supported on little-endian devices. | ### Sega #### Dreamcast/Naomi | Core | Supported | Notes | |----------------------------------------------------|:---------:|:------| | [Flycast](https://github.com/libretro/flycast) | ✔ | Must disable threaded rendering to use save states. RetroArch 1.10.1 or higher required. | #### Master System / MegaDrive - Genesis | Core | Supported | Notes | |----------------------------------------------------------------|:---------:|:------| | [Genesis Plus GX](https://github.com/libretro/Genesis-Plus-GX) | ✔ | Preferred core. | | [BlastEm](https://github.com/libretro/blastem) | ✕ | Cycle accurate. Genesis/MegaDrive only. Has known issues with game RAM and is incompatible with achievements. | | [ClownMDEmu](https://github.com/Clownacy/clownmdemu-libretro) | ✔ | | | [Picodrive](https://github.com/libretro/picodrive) | ✔ | | | [SMS Plus GX](https://github.com/libretro/smsplus-gx) | ✔ | Master System only | | [Gearsystem](https://github.com/drhelius/Gearsystem) | ✔ | Master System only | | [Emux SMS](https://github.com/libretro/emux) | ✕ | | | [FinalBurn Neo](https://github.com/libretro/FBNeo) | ✕ | | #### 32X / 32X CD | Core | Supported | Notes | |----------------------------------------------------|:---------:|:------| | [Picodrive](https://github.com/libretro/picodrive) | ✔ | Emulation quality can be dodgy. | #### Game Gear | Core | Supported | Notes | |----------------------------------------------------------------|:---------:|:------| | [Genesis Plus GX](https://github.com/libretro/Genesis-Plus-GX) | ✔ | | | [SMS Plus GX](https://github.com/libretro/smsplus-gx) | ✕ | | | [Gearsystem](https://github.com/drhelius/Gearsystem) | ✔ | | | [FinalBurn Neo](https://github.com/libretro/FBNeo) | ✕ | | #### SG-1000 | Core | Supported | Notes | |----------------------------------------------------------------|:---------:|:------| | [Genesis Plus GX](https://github.com/libretro/Genesis-Plus-GX) | ✔ | Preferred core. | | [SMS Plus GX](https://github.com/libretro/smsplus-gx) | ✕ | | | [Gearsystem](https://github.com/drhelius/Gearsystem) | ✕ | | | [blueMSX](https://github.com/libretro/blueMSX-libretro) | ✔ | | | [FinalBurn Neo](https://github.com/libretro/FBNeo) | ✕ | | #### Sega CD - Mega-CD | Core | Supported | Notes | |----------------------------------------------------------------|:---------:|:------| | [Genesis Plus GX](https://github.com/libretro/Genesis-Plus-GX) | ✔ | | | [ClownMDEmu](https://github.com/Clownacy/clownmdemu-libretro) | ✔ | | | [Picodrive](https://github.com/libretro/picodrive) | ✔ | | #### Saturn | Core | Supported | Notes | |-----------------------------------------------------------------------|:---------:|:------| | [Beetle Saturn](https://github.com/libretro/beetle-saturn-libretro) | ✔ | Preferred core. High accuracy, but low speed | | [Yabause](https://github.com/libretro/yabause/tree/master) | ✕ | Technically supported, but use at your own risk. Higher speed | | [Kronos](https://github.com/libretro/yabause/tree/kronos) | ✕ | Technically supported, but use at your own risk. High speed, supports graphic enhancements, but requires a GPU that supports at least OpenGL 4.2 | | [YabaSanshiro](https://github.com/libretro/yabause/tree/yabasanshiro) | ✕ | | ### SNK #### Neo Geo Pocket / Neo Geo Pocket Color | Core | Supported | Notes | |------------------------------------------------------------------|:---------:|:------| | [Beetle NeoPop](https://github.com/libretro/beetle-ngp-libretro) | ✔ | | | [RACE](https://github.com/libretro/RACE) | ✕ | | | [FinalBurn Neo](https://github.com/libretro/FBNeo) | ✕ | | ### Sony #### PlayStation | Core | Supported | Notes | |------------------------------------------------------------------|:---------:|:------| | [Beetle PSX HW](https://github.com/libretro/beetle-psx-libretro) | ✔ | Preferred core. Identical to Beetle PSX, with extra hardware features. High accuracy. | | [Beetle PSX](https://github.com/libretro/beetle-psx-libretro) | ✔ | Identical to Beetle PSX HW in software mode. | | [SwanStation](https://github.com/libretro/swanstation) | ✔ | Fork of DuckStation. Fairly high accuracy, extremely high speed. | | [PCSX ReARMed](https://github.com/libretro/pcsx_rearmed) | ✕ | Technically supported, but use at your own risk. Lower accuracy than Beetle PSX (HW), higher speed. | #### PlayStation Portable | Core | Supported | Notes | |-----------------------------------------------|:---------:|:------| | [PPSSPP](https://github.com/hrydgard/ppsspp/) | ✔ | RetroArch 1.9.9 or higher required | ### The 3DO Company (various manufacturers) #### 3DO | Core | Supported | Notes | |-----------------------------------------------------|:---------:|:------| | [Opera](https://github.com/libretro/opera-libretro) | ✔ | If you run into issues, try switching to a different BIOS. | ### WASM-4 | Core | Supported | Notes | |------------------------------------------------|:---------:|:------| | [WASM-4](https://github.com/aduros/wasm4) | ✔ | RetroArch 1.10.2 or higher required | ### Watara #### Supervision | Core | Supported | Notes | |------------------------------------------------|:---------:|:------| | [Potator](https://github.com/libretro/potator) | ✔ | RetroArch 1.9.2 or higher required | ### Misc | Core | Supported | Notes | |------------------------------------------------|:---------:|:------| | [VaporSpec](https://github.com/libretro/libretro-common/tree/716bb5e7b761a3b4d44e069c84491d906d32aba0) | ✕ | | ================================================ FILE: docs/guides/navigating.md ================================================ # Navigating Navigating on RetroArch is as easy as you can imagine. Depending on the device you have, the control scheme is determined automatically. For example, if you are going to use it on a computer, the basic key combinations of the keyboard will apply. You move with the arrow keys and select with the *Enter* key, and you return with the *Backspace* key. If you plug a controller, you can also move with the D-Pad buttons. The default [GUI](GUI) for RetroArch is [Ozone](ozone.md). While the "skin" may differ on certain platforms, basic layout and navigation remains broadly the same. ## PC By default the keyboard should be ready to use. Using the *left* and *right* arrow keys, you move to a different tab, each tab will relate to an aspect of the RetroArch experience (main menu for game loading, settings for settings etc.). Once the desired tab is selected, use the *up* and *down* arrow to move to an option. To advance in the menu press *Enter* (or *Return*). To go back to the previous menu push *Backspace*. Whilst in a game use the *F1* key to open the [Quick Menu](quick-menu.md). Pushing *Esc* twice will quit the program. ### Main Menu ![Ozone's Main Menu](../image/retroarch/ozone/first_run.webp) Welcome to the main menu. This is where you will launch games, download and update cores, and have access to freely available content. *Load Core*, *Load Content* and the *Online Updater* are the menu items you will probably be using the most. *See [Starting a Game](starting-a-game.md)* ### Settings ![Settings](../image/retroarch/ozone/settings.png) Here you will find all the options available to configure RetroArch, from Graphics, Input, Sound and everything else. ### Favorites ![Favorites](../image/retroarch/ozone/favorites.png) Favorites allow yous to maintain a short list of games for quick access. You can add content to this playlist from the [Quick Menu](quick-menu.md) or before launching it. ### History ![History](../image/retroarch/ozone/history.png) Recently launched content will be added to this Playlist. The content you ran last will be at the top. ### Image, Music and Video These tabs will handle all your media. Images will contain any screenshots you've made. ### Netplay RetroArch relies on peer-to-peer networking to reduce network latency and ensure the best possible experience. It allows multiplayer over the internet. The user can host or join a network gaming session, or use the Spectator mode to watch others play. RetroArch has a built-in netplay lobby. ### Import content ![import-content](../image/retroarch/ozone/import-content.png) Either you scan automatically, so that any content that matches the internal database will be added to Playlists, or you scan manually, not being dependent on the database so you can freely add your content to Playlists. ## Mobile The mobile interface, [GLUI](glui.md), is more minimalistic compared to the PC's interface. Touch is the default input, although depending on device other options may be available. There are three different tabs, which can be switched at the bottom of the menu. ### Main Menu ![GLUI's Main Menu](../image/retroarch/glui/glui-main.png) The main menu will be where you launch games, download and update cores, start or join netplay sessions and pretty much anything to do with gaming. *See [Starting a Game](starting-a-game.md)* ### Playlists Handles anything to do with creating and maintaining playlists. It gives you scanning options to recognise your game collection. It also provides access to your images, music and videos. ### Settings Here you will find all the options available to configure RetroArch, from Graphics, Input, Sound and everything else. ================================================ FILE: docs/guides/netplay-faq.md ================================================ ![](../image/branding/netplay-logo.gif) ## FAQ ### What is netplay? - Netplay is RetroArch's mechanism for emulating local multiplayer over the internet, by continuously synchronizing multiple RetroArch instances running the same emulation core and same content. Currently, this approach is only for emulating classic single-system local multiplayer, not link cable play or network multiplayer modes. ### Does RetroArch require port-forwarding to work? - The host needs to accept incoming connections on port TCP 55435. For most people, this requires port-forwarding: the network connections have to be forwarded from your local network access point (i.e. gateway or router) to the device running RetroArch. RetroArch requests a port-forwarding from the local network using the UPnP IGD protocol, or, you can manually create a port-forwarding rule on your network device. For those who can't forward the ports for whatever reason, please refer to the Setup Guide below. ### Does it support more than two players? - Yes! See [Getting Started Guide](netplay-getting-started.md) for more details. ### Does it support more than one player on one computer? - Yes! See [Multiple Controllers Guide](netplay-multiple-controllers.md) for more details. ### Does it support the host spectating while a client performs as player 1? - Yes! By default, the host is always assigned Controller 1, but see [Multiple Controllers Guide](netplay-multiple-controllers.md) on how a client can 'Request Device' to be controller 1. ### What do you need for RetroArch netplay to work? - Same RetroArch version, same core version, and the same exact content. ### Does RetroArch support cross-platform netplay? - Yes, but your mileage may vary, particularly when endianness differs. ### Which cores work for netplay? - On a technical level, every core that supports save states should work but the performance requirements may be too high for it to work in any practical level. ### Does PSX / N64 / Dreamcast / GameCube / Wii / 3DS netplay work? - No, the performance requirements make the current model unsuitable for those. ### Can I play GB / GBC / GBA / PSP / 3DS games with multiple people via RetroArch Netplay? - No, RetroArch's netplay is not link-cable emulation, GB, GBA, PSP netplay are currently not possible with our implementation. One notable exception is same game GB/GBC Netplay via the TGB-Dual and Sameboy cores. ### Can I trade Pokémon via RetroArch Netplay? - Yes. For now, the only two cores providing this functionality are gpSP (it emulates the GBA wireless adapter) and MelonDS DS (a MelonDS fork that lets you use GTS). ## Troubleshooting NetPlay ### RetroArch says "Content not found, try loading content manually" - Either load content manually, have the content in your recent history list, or scan your content to a playlist. ### As Client: "Failed to Initialize Netplay" "Failed to Initialize Netplay" often means you were not able to connect to the host. Confirm that you have the correct IP address for the host, and that the host has begun hosting a NetPlay session. Tell the host to check if their host-based firewall is allowing RetroArch to accept connections, and confirm that they have port-forwarding working. ### As Host: "Port Mapping Failed" "Port Mapping Failed" probably indicates a UPnP port-forwarding problem. If you can manually configure your network gateway to forward TCP port 55435 to the local-network IP address of your RetroArch device, then you can do that. Alternatively, enable the use of a Relay Server. ================================================ FILE: docs/guides/netplay-getting-started.md ================================================ ![](../image/branding/netplay-logo.gif) ## Getting Started ### Configure a Nickname - Navigate to **Settings** - Navigate to **User** - Select **Username** - Configure your preferred nickname ![Screenshot](../image/retroarch/netplay/nickname.png) ### Host a Netplay Server If you are going to host a game, simply configure your network parameters and "Start Hosting" from the netplay menu. After doing that, load the content you want to netplay and wait for players to connect. ![Screenshot](../image/retroarch/netplay/netplay.jpg) #### Check your lobby Once you start hosting, you can check to see if your lobby is visible [at lobby.libretro.com](http://lobby.libretro.com/). !!! tip If your router doesn't support UPnP, you can't forward your ports, or you are just uncertain how, enable the **Use Relay Server** option. This routes both sides of the connection through one of the public proxy servers. !!! tip If you want to run a private game, set up a **Server Password** to prevent random people from connecting. Alternatively, you can disable the **Publicly Announce Netplay** option. The clients will need to enter your IP address or hostname directly. !!! Warning By default, RetroArch attempts to use UPnP to automatically port-forward (it asks the gateway to forward incoming connections on TCP 55435 to itself), but it doesn't check to see if it succeeded (i.e., if it is actually reachable on TCP 55435 from elsewhere on the internet). The lobby server doesn't verify the host's reachability either. Make sure you have correctly port-forwarded, using [this tool](http://www.yougetsignal.com/tools/open-ports/): enter your **Netplay TCP Port** once you are hosting, and it will tell you if the port is open or not. If this port is not open, people won't be able to connect to your session, and you might have to enable the use of a Relay Server. ### Configure Netplay Clients You don't need to configure anything to connect to netplay rooms. Browse to the netplay menu, Select **Refresh** and then select the room you want to connect to. ![Screenshot](../image/retroarch/netplay/rooms.png) You will be asked for a password if one is required, and if you have matching content scanned or in the **Content History** it will connect right away. Otherwise, it will tell you to load the core and content manually and it will attempt to connect right away. ================================================ FILE: docs/guides/netplay-multiple-controllers.md ================================================ ![](../image/branding/netplay-logo.gif) ## Assigning Controllers During Netplay ### Request Device **Request Device** is an advanced network option used for NetPlay, that allows each RetroArch instance to request which device(s)/controller(s) to control. This, for example, enables four players from two instances of RetroArch, or for a connecting client to request the player 1 controller from the host. To make this option visible, RetroArch must have **Show Advanced Settings** set to _ON_. #### Turning on **Show Advanced Settings** - Navigate to **Settings** - Navigate to **User Interface** - Toggle **Show Advanced Settings** to _ON_ Once **Show Advanced Settings** is on, proceed to the **Network** configurations in the **Settings** menu (**NetPlay** menu also has a path to **Network** configurations). Scroll down through **Network** configuration, and the advanced configuration options are now visible. **Request Device #** _(where # is any number from 1 to 16)_ options will allow the computer to control any number of controllers during NetPlay. ## Example Setup: Step-by-Step Guide The following example of Super Bomberman 2 on the SNES will be used to demonstrate four players using two computers. The host will be controlling players 1 and 3, and the client will be controlling players 2 and 4. ### On the Host #### Configure Host's Input Devices Set up **Input Devices** while the game is loaded: - Connect two controllers - Start SNES Super Bomberman 2 game - Set **Inputs** for each controller 1 and 2: - Navigate to **Settings** - Navigate to **Inputs** - Navigate to **Port 1 Binds** - Ensure **Device Index** is set to *_Controller Name 1_ - Return to **Inputs** configuration menu - Navigate to **Port 2 Binds** - Ensure **Device Index** is set to *_Controller Name 2_ - Set **Device Type** to _MultiTap_ - _MultiTap_ is only available when SNES core is loaded. This plugs in a virtual SNES MultiTap into the SNES so more than two controllers can connect to the SNES. \* Controller Name 1 and 2 are unique to the computer and to the controllers connected to it (_e.g._, PS4 controller shows as "Wireless Controller \#1") #### Configure Host's Requested Devices Set host computer's RetroArch NetPlay to request control of the running core's devices/controllers: - Navigate to **Settings** -or- **NetPlay** - Navigate to **Network** - Set **Request Device 1** to _YES_ - Set **Request Device 3** to _YES_ - Ensure all other **Request Device #** are set to _NO_ Host is now able to start a NetPlay game controlling controllers 1 and 3. See [Getting Started Guide](netplay-getting-started.md) for more details. ![Screenshot](../image/retroarch/netplay/netplay_multiple_controllers_host.png) ### Client #### Configure Client's Input Devices Set up **Input Devices** while the game is loaded: - Connect two controllers - Start SNES Super Bomberman 2 game - Set **Inputs** for each controller 1 and 2: - Navigate to **Settings** - Navigate to **Inputs** - Navigate to **Port 1 Binds** - Ensure **Device Index** is set to *_Controller Name 1_ - Return to **Inputs** configuration menu - Navigate to **Port 2 Binds** - Ensure **Device Index** is set to *_Controller Name 2_ \* Controller Name 1 and 2 are unique to the computer and to the controllers connected to it (_e.g._, PS4 controller shows as "Wireless Controller \#1") #### Configure Client's Requested Devices Set client computer's RetroArch Netplay to request control of the running core's devices/controllers: - Navigate to **Settings** -or- **Netplay** - Navigate to **Network** - Set **Request Device 2** to _YES_ - Set **Request Device 3** to _YES_ - Ensure all other **Request Device #** are set to _NO_ Client is now able to join the Host in a NetPlay game controlling controllers 2 and 4. See the [Getting Started Guide](netplay-getting-started.md) for more details. ![Screenshot](../image/retroarch/netplay/netplay_multiple_controllers_client.png) !!! Warning RetroArch **Network** typically has all **Request Device #** set to _NO_. When all **Request Device #** are set to _NO_, this allows NetPlay to automatically set host as device/controller 1. When the client connects to the host, the client will connect to device/controller 2 for the NetPlay session. Each subsequent client that connects will continue connect to the next available device/controller. For this automatic client-to-controller assignment in a RetroArch NetPlay session to work, all **Request Device #** settings must be set to _NO_. If any connecting clients request a device, automatic assignment is disabled for everyone and all clients must request a device via the settings menu. ================================================ FILE: docs/guides/optimal-vsync.md ================================================ # Getting Optimal Vsync Performance RetroArch uses [Dynamic Rate Control](ratecontrol.pdf) to synchronize both video and audio at the same time. Synchronizing in this way is a very demanding task timing-wise and dynamic rate control helps smooth out imperfections in timing which are guaranteed to arise. However, when Dynamic Rate Control is functioning as intended, the frame pacing and audio synchronization will be perfectly smooth. It can be disabled, but be aware that proper video/audio sync is nearly impossible to obtain in that case. !!! tip +In order to propose improvements to this document, [visit it's corresponding source page on github](https://github.com/libretro/docs/tree/master/docs/guides/optimal-vsync.md). Changes are proposed using "Pull Requests." ## Basic Configuration While using RetroArch, the default settings might not be adequate, and you might experience video stuttering and/or audio crackling. For correct synchronization, `Settings->Video->Output->Vertical Refresh Rate` must be configured for your display. It cannot be detected accurately enough by OS-provided APIs (i.e. they tend to blatantly lie). For proper behavior, an accuracy of roughly ~0.1% is needed for dynamic rate control to smooth out the drifting. This is trivial to obtain by measuring manually under normal conditions. Without dynamic rate control one would need a "perfect" measurement which obviously isn't possible without special hardware. RetroArch gives you an estimate of your display's refresh rate at `Settings->Video->Output->Estimated Screen Refresh Rate`, which is updated in real-time using a running average over frame times. Make sure VSync is enabled and working. Also make sure you're running in full-screen for more accurate results (compositors can easily interfere with timing). Press accept button on the estimated refresh rate to configure RetroArch with the estimated rate. If the running average isn't drifting much anymore, it's probably a good result. You can also have RetroArch log the output at the end and configure things more manually. Start RetroArch directly in RGUI with `retroarch --verbose --menu`. Let it run uninterrupted for at least 4096 frames (displayed in title bar), and exit. In the log, you should see something like: ``` RetroArch: Average monitor Hz: 59.869485 Hz. (1.347 % frame time deviation, based on 2048 last samples). ``` If you're unsure about the result, run this test several times and see if the results are consistent. Some systems tend to have very unreliable VSync behavior and this result will wildly fluctuate. You can use this value in `Vertical Refresh Rate` and the video and audio should ideally be exceptionally smooth without any static or 'popping' audio. If you have ensured your refresh rate is dialed in well, and this is still not the case, read on. ## Advanced Configuration Considerations If you continue to find the audio and/or video output after the above basic configuration to be incorrect or insufficient, there are a multitude of settings and other factors, both inside of RetroArch and external to the program, that can have a significant impact on your ability to obtain smooth frame pacing and proper synchronization. Adjusting these settings in a haphazard fashion or adjusting more than one at a time can lead to skipping over a correct solution by fixing one part of the problem while simultaneously breaking another part. If instead it does work afterwards, then it can lead to an inability to determine which change actually contributed to success. The next section is an attempt at a step by step guide to configuring and diagnosing most frame pacing related settings. It is ordered starting from the most critical and directly audio/visual synchronization related settings first and continues towards settings that have other uses and effects, yet also impact synchronization, farther down. You can skip over any configuration changes you are unwilling to compromise on just for possibly improved frame pacing, or stop after any point in the process that you are satisfied with the output, of course. If you want to be able to judge the impact of a setting change by more than just 'eyeballing' the results, RetroArch provides a running statistics HUD by toggling `Settings->User Interface->On-Screen Display->On-Screen Notifications->Notification Visibility->Display Statistics`. You can also use an external program to monitor frame pacing, but keep in mind just the act of running it is possibly introducing a small amount of jitter itself. Notable internal RetroArch statistics regarding frame pacing are: - Core AV_INFO->FPS - The exact frame timing the core is requesting. - Video->Refresh - What your `Settings->Video->Output->Vertical Refresh Rate` is currently set to. - Video->FPS - The rate at which you are currently outputting actual frames. With VRR on, this should match `Core AV_INFO->FPS`, and with VRR off, this should be very close to `Settings->Video->Output-Vertical Refresh Rate` divided by `Vsync Swap Interval` after the averaging settles. If `Video->FPS` is far above these values, possibilities include your Vsync or your VRR settings are not engaging properly, depending on which you are using, while having `Settings->Audio->Synchronization->Synchronization` disabled. If instead `Video->FPS` is substantially beneath, possibilities include Swap Interval set wrong, or your hardware not being able to keep up with the system demands. Note that neither `Video->FPS` nor `Core AV_INFO->FPS` will display 30 for 30 fps content most of the time, as internal frame doubling is performed. - Audio->Underrun - This keeps track of the amount of time slices over a recent period that the audio buffer is near emptying. If this value settles at a percentage higher than 0%, after running for a while (and without menu access, slow motion, or fast forward having recently been used), you can use this to diagnose that the audio and video aren't in great sync, as the audio is not keeping up with the video. In this situation RetroArch will either occasionally stutter briefly to maintain sync, or if `Settings->Audio->Synchronization->Synchronization` is off, you will get static and popping audio noises. - Audio->Blocking - The opposite of `Audio->Underrun` in practice. This time, if it settles at a percentage higher than 0%, after running for a while (and again, without menu access, slow motion, or fast forward having recently been used), it means the audio is running ahead of the video. Note that on some cores it is possible to have moderate amounts of *both* Underrun and Blocking present while your hardware is capable of performing at full core requested speed and all settings are correct, but this is more common for actual variable framerate content that tends to be more present from the 5th generation of consoles on. So it might be best to test your overall settings with an earlier generation, less complex core. ## Advanced Configuration Step-By-Step Guide 1. Choose one of the following synchronization methods depending on whether your screen is capable of Variable Refresh Rate (VRR) and if you want to use it: - For synchronization without VRR, you should set `Settings->Video->Output->Vertical Refresh Rate` very close to an evenly divisible multiple of the core requested refresh rate, still using `Settings->Video->Output->Estimated Screen Refresh Rate` to get a more accurate value as mentioned in the Basic Configuration section. You should end up with a value right around 60/120/180/240/etc Hz for NTSC, 50/100/150/200/etc for PAL. Uneven, but fairly common, display refresh rates like 75/90/144/165 Hz are only able to maintain smooth frame pacing and audio synchronization while `Variable Refresh Rate (VRR)` is active, which is discussed below. Setting your actual display refresh rate to 60Hz, and then configuring the real refresh rate as per the Basic Configuration section, combined with a complementary `Vsync Swap Interval` of 1, will always be the most default and thus supported mode of operation to obtain perfect frame timing. But if you want to be able to run RetroArch on your >60Hz display without having to lower the actual screen refresh rate, this section explains how to do so correctly with minimized chance of issues. After you have verified the rate is set appropriately, you should check under `System->Video Settings->Synchronization` and make sure that `Vertical Sync (Vsync)` is on, and set the `Vsync Swap Interval` to either `Auto`, which will try to determine the right value for your applied refresh rate on its own, or you can manually set the value yourself. Unless you note specific issues with your system, `Auto` is likely the superior choice, as it will avoid the 'math problem' required for manual configuration and respond to changes in others settings including `Black Frame Insertion` and `Sync to Exact Content Framerate (G-Sync, Freesync)` without needing to be updated again itself. If you choose to set it manually, the value you should set it to is the value such that when you divide `Settings->Video->Output-Vertical Refresh Rate` by it, gives you a result near your 60/50Hz goal. I.e. 60Hz/1 = 60Hz, so set `Vsync Swap Interval` to 1. 120Hz/2 = 60Hz, so set `Vsync Swap Interval` to 2, 180Hz/3 = 60Hz so set `Vsync Swap Interval` to 3, and so on. Lastly, when syncing with this method to a value other than `Auto` or 1, ensure that `Black Frame Insertion` is off, and that `Sync to Exact Content Framerate (G-Sync, Freesync)` is off. These are each separate methods to sync the display and audio, and they should not be combined. - For a VRR capable display, configuring settings is less error prone, at least inside of RetroArch, and also has a benefit of being able to sync to the exact originally intended speed of the core. `Settings->Video->Output->Vertical Refresh Rate` will not be in use to attempt to adjust the timing, and is not required to be set correctly, but it is still good practice. To setup RetroArch to use VRR timing, turn on `Sync to Exact Content Rate (G-Sync, Freesync)` under `System->Video Settings->Synchronization`, and verify `Vsync Swap Interval` is set to either 1 or Auto, and that `Black Frame Insertion` is off. Just as above, these settings should not be combined. 2. Ensure `Settings->Audio->Synchronization->Synchronization` is enabled. Also in this same menu, for a non-VRR setup, `Maximum Timing Skew` will decide how far Retroarch will be willing to adjust the core requested speed to attempt to sync with your refresh and swap interval settings. For the most part, the default value will be fine, but some arcade content runs at Hz significantly farther in the middle between 50Hz and 60Hz. The older Mortal Kombat arcade machines request a rate around 54Hz, for instance. Further, if you desire to run 50Hz PAL content at 60Hz NTSC speed, you must set the maximum skew even higher. 60Hz NTSC is ~17% faster than 50Hz PAL, so you would want to set the `Maximum Timing Skew` to .17. Note that a higher maximum will not cause content that is not far from your set refresh rate to run at a less correct speed, it will only allow content that is farther away to sync so that you can obtain smooth frame pacing and audio. 3. Check Display Control Panel and Other External Program Settings - Make sure you are not overriding application settings to force `Vsync` off. - Check if you decided to use VRR in step 1. * If you aren't using VRR, and have a maximum framerate cap set (in the driver or through a third party software tool like RTSS), verify that it is at least as high as the set refresh rate of your display. You might think a 60 fps cap would be all you need for 60 fps content, but a display set to 240Hz using a swap interval of 4, still needs 240 potential vblanks per second to sync correctly to 60 actual fps. * If you are using VRR, you must verify that it enabled at the display driver level, and on the display as well. Also you should ensure, if you have a configured maximum framerate cap, that it is set slightly above 60 at the least, not right at 60. NTSC NES/SNES request 60.1Hz for instance, and this could interfere with proper frame timing even with VRR, if you have a 60 fps framerate cap. - If your system has a strong GPU and it is available for your display driver, consider looking for a setting similar to `Power Management Mode` and configure it for `Prefer Maximum Performance`, either globally or specifically for RetroArch. Some higher powered GPU's are designed to downclock on lower loads by default, which they may see RetroArch as. If your GPU can stay in this downclocked state while maintaining full performance, there might not be any interference with smooth synchronization. However, if instead if it responds to RetroArch as a load where it constantly shifts back and forth between a high power state and a low power state, this can cause inconsistent frame times. - Consider disabling possibly unnecessary overlays like from RTSS, Discord, or Steam. RTSS has been known with previous versions, for instance, to cause issues with Vulkan in Retroarch, even when not running, just merely by being installed! For reference: [Vulkan Frame Pacing Stutter](https://github.com/libretro/RetroArch/issues/9668) - Active video recording or streaming software has the potential to interfere with perfect frame pacing, but if your stream or recording is important, obviously perfect frame pacing will have to become a secondary concern. Just set all other settings as appropriately as you can. 4. Back inside of RetroArch consider adjusting settings that can have an impact on frame pacing and synchronization. - Windowed mode, and even windowed full-screen mode can contribute to frame pacing issues, so `Settings->Video->Fullscreen Mode->Windowed Full-Screen Mode` can be disabled to test if this improves your frame pacing. - `Settings->Video->Output->Automatic Refresh Rate Switch` can be considered to be disabled, as if it changes your actual display refresh rate, in non-VRR mode this can interfere with your set Vsync Swap Interval and cause *large* mistiming, and in VRR mode, you want the display to maintain the maximum potential refresh rate so that it can be more accurate in accomodating small requested timing differences. - `Settings->Video->Output->Threaded Video` is well known to interfere with smooth frame pacing and audio sync, but can be the only choice for hardware otherwise too weak for the intended content to run at near the correct frame rate at all. - Using a very heavy shader like an accurate CRT emulation shader, especially on a higher resolution display, can also increase performance requirements to obtain smooth synchronization. - Your preferred renderer API of Vulkan/OpenGL/DirectX 11/etc might not interact perfectly with your system or the core you are using, and you can try an alternative. - Core specific settings can be checked for things such as overclocks which can increase system requirements to where you might not be able to run full speed, or internal run-ahead, or frame duplication. - Under `Settings->Latency`, `Frame Delay (ms)`, `Automatic Frame Delay`, `Run-Ahead to Reduce Latency` and `Run Pre-Emptive Frames` should be adjusted down or off if smooth frame pacing is a priority for you over latency and you continue to have issues at this point in the process. These settings can cause inability to reach proper sync if your system can not handle the increased load or they are simply set too high even on very capable hardware. - `Settings-Latency->Audio Latency` perhaps unintuitively should be kept higher, not lower. Too low of an audio latency causes RetroArch to stutter while waiting to refill the now smaller audio buffer when `Settings->Audio->Synchronization->Synchronization` is enabled, or can cause very poor audio output when `Settings->Audio->Synchronization->Synchronization` is not set. How low you can set this to without issue can vary per content, but the default value of 64 ms was chosen for avoiding issues like this. If you still decide to push lower, keep in mind a 60Hz NTSC frame is approximately 16.66 ms long, so you might want to try a value a little longer than 2 frames, like 35ms, and then a little longer than 3 frames like 52ms, et cetera. - Under `System->Video Settings->Synchronization`, `Hard GPU Sync`, `Max Swapchain Images`, or `Waitable Swapchains`, any of which might be available with your current renderer API, are designed to reduce latency by limiting how many frames ahead that the cpu can calculate beyond the currently displayed frame. If you are still experiencing frame pacing issues having reached this poing in the document, and care more about that than increased latency, you can disable `Hard GPU Sync`, `Waitable Swapchains`, or increase the value of `Max Swapchain Images` to give your system more performance headroom. ## Further Considerations If you've gone through all the above, there is not much more to configure settings-wise. It is possible your hardware is just not capable of running the desired content at full speed. You can try to see if an alternative core exists for your content that is perhaps designed to run on lower specification hardware than the one you were previously using. Also (though no specific offenders will be named as this can change for better or worse with any core update any given day) some content on some cores simply have somewhat poorer timing control. Odds are higher of finding this on 5th generation and beyond console cores that are dealing with content that ran at very unstable framerates on original hardware. Lastly, a couple things to keep in mind that don't fit neatly in any section above without being a large digression: - Most VRR displays have a feature called Low Framerate Compensation (LFC). What this means is that there is a minimum fps below which VRR can no longer actually sync, and it will compensate for this with , depending on display implementation, a combination of internal frame doubling and screen tearing. If this rate is right near the output rate, and some 240Hz+ displays are indeed coming with a LFC minimum rate directly around 60 as of this writing, you can experience significant impact on frame pacing. 30 fps content will also be below this LFC rate on a large number of VRR displays, but if it is a very stable 30 fps and the display has a good frame doubling algorithm, this might not be an issue. If you check your display specifications and believe you are experiencing LFC related issues, you might well be better served using a fixed refresh rate for RetroArch. Note that you should not have to disable VRR in your display driver or on your display, just discontinue use of `Sync to Exact Content Rate (G-Sync, Freesync)` inside Retroarch, and instead follow the instructions above for using `Vsync Swap Interval` to sync. - It has been noted previously that for macOS, that having more than one display active can cause interference with obtaining good frame pacing and audio synchronization. This can be extended as a possible solution to try regardless of operating system. Relatedly, it is potentially helpful if you *do* leave multiple displays active, to leave them all set to the same refresh rate. Also, running videos or other screen updating content at the same time on a secondary display is a potential source of issues. Windows 10/11 compositor handles multiple active contents like this better as of writing than in the past, but this could change at any point and there are also a multitude of other Operating Systems and devices that will have their own possible compositor issues with running multiple separate contents simultaneously. **Thanks for reading, and have a smooth day!** ================================================ FILE: docs/guides/overlay-pointing-devices.md ================================================ # Overlay Mouse, Lightgun, and Pointer When using an overlay, RetroArch can send pointing device input alongside gamepad input using `Enable Overlay Lightgun, Mouse, and Pointer` in the `On-Screen Overlay` menu. This allows more natural control of lightgun overlays, emulated touchscreens, mouse-controlled first-person shooters, and anything else requiring simultaneous button \+ pointer input. **Note:** This overrides any platform-specific touchscreen controls, which might behave differently. ## Mouse behavior Dragging 1 finger moves the mouse cursor. 1-, 2-, and 3-finger taps are left, right, and middle mouse button clicks. By default, a 0.2s long press begins holding a button, and you'll feel haptic feedback when it starts. A double-tap hold method is also available but adds some latency to clicks. With either method, dragging 2 or 3 fingers immediately holds the right or middle button. There are settings for mouse speed, long-press and double-tap time thresholds, and a "swipe threshold" to distinguish swipes from taps and long presses. ## Lightgun behavior Lightgun x, y, and trigger are normally sent together to every lightgun port. There are settings to choose the port, disable the trigger, delay the trigger, and clamp off-screen aim to the in-bounds edge. The trigger delay is needed for content that doesn't instantly move the gun cursor to a screen tap. More lightgun buttons can be assigned to 2-, 3-, and 4-finger inputs. The trigger delay is used to wait for the correct multi-touch count. A 1-frame delay is usually enough to distinguish these inputs. **Note:** A few cores have a `Touchscreen` option for lightgun input. That needs to be set to `Lightgun` for this. ================================================ FILE: docs/guides/overrides.md ================================================ # Using Content, Folder, and Core Overrides for Custom Settings There are various and comprehensive ways to save customized settings within the RetroArch menus. 99% of settings can be adjusted and saved from the menu but are only plain text files and can be adjusted manually with a text editor. - Global settings can be overridden on a per core, per content directory, or per game basis using the config override system. - Input settings are handled separately with the input core and game Remap system. - Likewise, Shader Preset settings are also their own entity for per core and game settings - A standalone file also saves the Option settings for all cores that support them. The settings in this file can be overridden on a per game basis. !!! tip Please read the [Getting Started](install-windows.md) guide. ## Logic ### Overrides *(.cfg)* & Remaps *(.rmp)* Overrides and Remaps are designed to be lightweight and easily maintained configuration methods. They save only settings that differ from the preceding settings files. For example if only one setting differs between your `retroarch.cfg` and a `core.cfg`, then the `core.cfg` file will only contain one setting. The hierarchy for loading is: 1. Game settings -> Applied when loading a particular game (content) 2. Content directory settings -> Applied when loading content from a particular directory 3. Core settings -> Applied when loading content with a specific core 4. Default settings -> The default settings from 'retroarch.cfg' The RetroArch loading process is: - Load `retroarch.cfg` - Apply `.cfg` & `.rmp` override - Apply `.cfg` & `.rmp` override - Apply `.cfg` & `.rmp` override !!! note Core-specific or content directory-specific overrides that are not in game-specific overrides persist and will be loaded. Also once you have created an override any future changes will need to be saved via the Quick Menu. ### Options *(.opt)* & Shader Presets *(.cgp|.glslp|.slangp)* Custom per game core options and shader presets work slightly differently. These are full configurations and are loaded instead of the base shader preset and core option settings. ## Configuration Files & Location !!! note Depending on your chosen platform the location of these files after installation may vary. !!! warning Some settings cannot be saved in an override file from the menu. You can manually add settings to the override file to workaround most situations. **The default and global settings file** - `retroarch.cfg` *(located in the base install path)* **The global file for core option settings, for cores that support options** - `retroarch-core-options.cfg` *(located with the `retroarch.cfg`)* ### Core options - `name-of-game.opt` **If not found load** - `retroarch-core-options.cfg` The options files list the settings found under `Quick Menu -> Options`. The `retroarch-core-options.cfg` is created automatically on loading a core that supports Options. A game-specific options file is created when you select `Quick Menu -> Options -> Game-options file`. *(located in `/config//.opt`. The path is set under `Settings->Directory->Config`)* !!! attention Load Content Specific Core Options Automatically must be set to On in RetroArch's Configuration settings in order for game-specific options to be automatically loaded upon content load. ### Override Configs The override system activates on loading of content. RetroArch applies config settings with the logic as [explained above](#logic). **Per Core Override** - `/config//name-of-core.cfg` *(This path is set under `Settings -> Directory -> Config`)* These settings files are created from the `Quick Menu -> Save Core Overrides` option and contain ANY (supported) settings you have changed since loading content. These settings will be loaded every time you load content with that core. **Per Content Directory Override** - `/config//name-of-content-directory.cfg` *(located with per core override)* These settings files are created as above with the `Quick Menu -> Save Content Directory Overrides`. The settings will take precedence over `name-of-core.cfg` **Per Game Override** - `/config//name-of-game.cfg` *(located with per core override file)* These settings files are created as above with the `Quick Menu -> Save Game Overrides`. The settings will take precedence over `name-of-content-directory.cfg` ### Input Remaps Input remaps use the same logic as core/directory/game overrides and use the `.rmp` extension. They can be adjusted and saved from: - `Quick Menu -> Controls -> Save Core Remap File` - `Quick Menu -> Controls -> Save Content Directory Remap File` - `Quick Menu -> Controls -> Save Game Remap File` Set the save directory in `Settings -> Directory -> Input Remapping` *(by default they will save to `/config/remaps//`)* ================================================ FILE: docs/guides/ozone.md ================================================ # Ozone (GUI) **Ozone** is the default graphical user interface (gui) of RetroArch. Based on the Switch's menu design, this menu driver was introduced in RetroArch 1.7.6. ![Ozone's startup screen](../image/retroarch/ozone/first_run.webp) |DISCLAIMER| |----------| |Keyboard key assignments may differ by platform and configuration: Most of the examples below are for PC.| ## Menu structure Ozone's main categories and playlists are in a column on the left, and subcategories are in a panel to the right. A third column will appear on the right hand side when certain selections are made. ![Ozone's menu structure](../image/retroarch/ozone/menu-structure.png) Entering a subcategory will hide the top-level menu's text labels. When you return to Main Categories, the descriptions will reappear. The sidebar does not collapse while in Main Menu or Settings. If you want the labels to always be hidden, go to `Settings> User Interface> Appearance`, then turn `Collapse the Sidebar` on. ![Ozone's menu structure (History menu)](../image/retroarch/ozone/menu-structure-2.png) ### Navigating the menus Ozone is controlled like any other user interface. Regular input binds will apply, and binds here are defined in terms of the RetroPad, RetroArch's gamepad and joystick abstraction. | Controller | Default PC | Action | | ------------ | ---------- | ------ | | **A button** | Z/ENTER/Left mouse click | Accept/OK | | **B button** | X/Backspace/Right mouse click | Back/Cancel | | **D-pad Up/Down/Left/Right** | Arrow keys | Scroll through menu options | | N/A | **Right shift** | Toggle description label | | N/A | **S key** | Toggle search | | N/A | **F1** | Toggle quick menu | | N/A | **F5** | Toggle desktop menu | See [Input and Controls](input-and-controls.md). ### Searching through lists with the keyboard When using a keyboard, it can be slow to navigate a large list using gamepad-like controls. To help this, you can type `/` (forward slash) or `S` (S key) at any time to bring up a search box. Type a search string and hit `Return`. The cursor should jump to the first entry that matches. The search will match mid-path strings. However, if a match is found at the beginning of the path (like when searching for the first letter), the start-of-path match will take priority. ## Input See [Input and Controls](input-and-controls.md). ## Thumbnails ![Ozone, example of a thumbnail](../image/retroarch/ozone/thumbnail-1.png) Thumbnails appear in a side bar on the right side of the screen. With a playlist item selected, you can press the `spacebar` on your keyboard to toggle the full-screen view on/off. The default thumbnail is Boxart. Two thumbnails can be displayed simultaneously by going to `Settings> User Interface> Appearance` and enabling `Secondary Thumbnail`. The user can choose to display boxart, the title screen, or a gameplay screenshot. ![Ozone, full screen thumbnail](../image/retroarch/ozone/thumbnail.png) ## Audio Ozone has **OK**, **Cancel**, **Notice** and **Scroll** sound effects. It also has background music, created by [ViRiX Dreamcore](https://soundcloud.com/virix). These are turned off by default. To enable them, go to `Settings> Audio> Menu Sounds` and turn on the `Mixer`. Then in the same menu, turn on the sounds you want (the background music option is called `Enable BGM Sound`). ## Applying shaders See the [shaders user guide](shaders.md). ## Themes Ozone has a range of color schemes to choose from. They can be found in `Settings> User Interface> Appearance> Color Theme`. ![Ozone, examples of themes](../image/retroarch/ozone/ozone-themes.png) ================================================ FILE: docs/guides/ozone.md.backup ================================================ # Ozone (Menu Interface) **Ozone** is the default graphical user interface (gui) of RetroArch. Based on the Switch's menu design, this menu driver was introduced in RetroArch 1.7.6. ![Ozone's startup screen](../image/retroarch/ozone/first_run.webp) |DISCLAIMER| |----------| |Keyboard key assignments may differ by platform and configuration: Most of the examples below are for PC.| ## Menu Structure Ozone's main categories and playlists are in a column on the left, and subcategories are in a panel to the right. A third column will appear on the right hand side when certain selections are made. ![Ozone's menu structure](../image/retroarch/ozone/menu-structure.png) Entering a subcategory will hide the top-level menu's text labels. When you return to Main Categories, the descriptions will reappear. The sidebar does not collapse while in Main Menu or Settings. If you want the labels to always be hidden, go to `Settings> User Interface> Appearance`, then turn `Collapse the Sidebar` on. ![Ozone's menu structure (History menu)](../image/retroarch/ozone/menu-structure-2.png) ### Navigating the menu Ozone is controlled like any other user interface. Regular input binds will apply, and binds here are defined in terms of the RetroPad, RetroArch's gamepad and joystick abstraction. | Controller | Default PC | Action | | ------------ | ---------- | ------ | | **A button** | Z/ENTER/Left mouse click | Accept/OK | | **B button** | X/Backspace/Right mouse click | Back/Cancel | | **D-pad Up/Down/Left/Right** | Arrow keys | Scroll through menu options | | N/A | **Right shift** | Toggle description label | | N/A | **S key** | Toggle search | | N/A | **F1** | Toggle quick menu | | N/A | **F5** | Toggle desktop menu | See [Input and Controls](input-and-controls.md). ### Searching through lists with the keyboard When using a keyboard, it can be slow to navigate a large list using gamepad-like controls. To help this, you can type `/` (forward slash) or `S` (S key) at any time to bring up a search box. Type a search string and hit `Return`. The cursor should jump to the first entry that matches. The search will match mid-path strings. However, if a match is found at the beginning of the path (like when searching for the first letter), the start-of-path match will take priority. ### Starting a game * To load a game you need two things: A libretro core to act as a gaming system, and content (a ROM or ISO) to play on that system. * Select `Load Core` from the main menu to browse a list of installed cores. You need to select the core compatible with your content from the `core` list. * If you have no cores listed, or you want additional cores, click on `Download a Core` at the bottom of the list and make your selection(s). After loading a libretro core, you will see the name and version of the core in the bottom left of the window. You can then browse for a ROM via `Main Menu> Load Content`. To control where Ozone starts to browse for contents, set `File Browser` in `Settings > Directory`. If this is not set, the file browser will start in the user's root directory. See [File Browser](file-browser.md) and [Import Content](import-content.md) ## Thumbnails ![Ozone, example of a thumbnail](../image/retroarch/ozone/thumbnail-1.png) Thumbnails appear in a side bar on the right side of the screen. With a playlist item selected, you can press the `spacebar` on your keyboard to toggle the full-screen view on/off. The default thumbnail is Boxart. Two thumbnails can be displayed simultaneously by going to `Settings> User Interface> Appearance` and enabling `Secondary Thumbnail`. The user can choose to display boxart, the title screen, or a gameplay screenshot. ![Ozone, full screen thumbnail](../image/retroarch/ozone/thumbnail.png) ## Audio Ozone has **OK**, **Cancel**, **Notice** and **Scroll** sound effects. It also has background music, created by [ViRiX Dreamcore](https://soundcloud.com/virix). These are turned off by default. To enable them, go to `Settings> Audio> Menu Sounds` and turn on the `Mixer`. Then in the same menu, turn on the sounds you want (the background music option is called `Enable BGM Sound`). ## Applying shaders See the [shaders user guide](shaders.md). ## Input See [Input and Controls](input-and-controls.md). ## Themes Ozone has a range of color schemes to choose from. They can be found in `Settings> User Interface> Appearance> Color Theme`. ![Ozone, examples of themes](../image/retroarch/ozone/ozone-themes.png) ================================================ FILE: docs/guides/quick-menu.md ================================================ # Quick Menu The **Quick Menu** is effectively RetroArch's pause menu. ## Controls The Quick Menu can be accessed by pressing a certain gamepad combination, pressing the `F1` key on your keyboard, or tapping on the "Invader" or "Menu" button on most Gamepad Overlays. The RetroPad button combination for opening the Quick Menu can be changed at `Settings>Input> Hotkeys> Menu Toggle`. Users select the combination from a list (Custom combinations cannot be applied): * None * Done + Y + L1 + R1 * L3 + R3 * L1 + R1 + Start + Select * Start + Select * L3 + R1 * L1 + R1 * Hold Start (2 seconds) * Hold Select (2 seconds) * Down + Select * L2 + R2 ## Features ## The Quick Menu provides access to many core-specific settings and options while the content is paused in the background. Options include (but are not limited to) adjusting the video resolution and system region, remapping controller inputs, managing Load/Save States, cheats or shaders, and taking screenshots or recording video clips. ### Close Content The most important function exclusive to the Quick Menu (aside from `Resume Content`) is `Close Content`. This safely 'shuts off' the emulated system and its content, returning the user to RetroArch's main menu without having to quit RetroArch completely. ### Disc Control Another "exclusive" function that appears with certain cores is swapping discs using the `Disc Control` option: See [Disc Swapping](./disc-swapping). ================================================ FILE: docs/guides/recording-and-streaming.md ================================================ # Recording and streaming video from RetroArch RetroArch has the capability to record gaming footage in real-time using libavcodec (FFmpeg). Both lossless and lossy coding is supported. It is possible to configure most encoding options for libavcodec using a separate config file. ## FFmpeg version RetroArch requires a very recent version of FFmpeg to work correctly. If you are on Linux or OSX, your distros FFmpeg build is likely out of date, and you should build FFmpeg from Git. A recommended command line is: ```bash ./configure --prefix=/opt/ffmpeg --enable-libx264 --enable-gpl --enable-libmp3lame make sudo make install ``` This assumes you will install a custom FFmpeg build into `/opt/ffmpeg`. For Windows users, the redist includes recent enough libav* binaries. Now you can configure RetroArch with: ```PKG_CONFIG_PATH=/opt/ffmpeg/lib/pkgconfig ./configure``` and the configure script should pick up the FFmpeg libraries in `/opt/ffmpeg/lib`. Check config.mk to make sure. After successfully compiling, make sure that the RetroArch binary picks up the correct FFmpeg libs by adding `/opt/ffmpeg/lib` to LD_LIBRARY_PATH (or the equivalent on OSX). ## Lossless coding By default (not providing an encoding config), lossless coding is used. This means libx264/RGB, with -qp 0 (lossless). The audio codec used is FLAC. libx264/RGB ensures very nice bitrates even when lossless and very fast encoding. ## Lossy and flexible coding config By adding the `--recordconfig ` parameter, you have more control over encoding. The recognized config options are: ``` vcodec = # Same as -vcodec acodec = # Same as -acodec format = # Muxer format to use. E.g. mkv, flv or mp4. This is normally inferred, but must be set when using extensionless formats like RTMP (streaming). threads = # Threads to use when encoding video. Should be set to (# of CPU threads - 1). frame_drop_ratio = # Only encodes every frames. pix_fmt = # Same as -pix_fmt, no default is assumed, must be set! scale_factor = # Scales input by . Useful when encoding in chroma subsampled formats like yuv420p. sample_rate = # Audio output sampling rate. audio_global_quality = # Global quality for audio (VBR). Maps to codec->global_quality in API. Play around with it. Higher = better. 75 seems to be a fair value. audio_bit_rate = # Audio bit rate (CBR). This is in bit/s, so use e.g. 192000 for 192 kb/s. video_{option} = # Sets generic video option {option} to . This is codec specific. Mostly useful for libx264. audio_{option} = # Sets generic audio option {option} to . This is codec specific. ``` ## Live streaming RetroArch can live stream to RTMP services like [twitch](http://www.twitch.tv/). To live stream there, create a config that is tailored for twitch. Example: ``` vcodec = libx264 acodec = libmp3lame pix_fmt = yuv420p scale_factor = 2 threads = 3 video_crf = 25 video_preset = superfast video_tune = animation audio_global_quality = 75 sample_rate = 44100 format = flv ``` You can stream to twitch with a command such as: ```bash retroarch --record rtmp://live.twitch.tv/app/$YOUR_TWITCH_ID --recordconfig twitch.cfg ``` ================================================ FILE: docs/guides/retroachievements.md ================================================ # RetroAchievements In RetroArch ## **What are RetroAchievements?** [retroachievements.org](https://retroachievements.org/) is a service that provides a trophy/achievement unlocking mechanism similar to modern consoles, for retro games. !!! Warning The service is not maintained by RetroArch or the Libretro team. !!! Warning In order to get better compatibility with the RetroAchievements feature it's recommended to always use the latest version of RetroArch and the cores. ## **How to setup achievements** 1. Register an account on [retroachievements.org](https://retroachievements.org/) (don't forget to confirm your account creation with the email they send to you). 2. Open Retroarch and go to Settings->Achievements. 3. Enable the functionality and fill in your retroachievements credentials. !!! Note The hardcore mode prevents you from using emulation features like savestates, slow motion, and cheats, **BUT** it places you on a separate leaderboard and allows you to participate in site events. ![](../image/retroarch/retroachievements/achievements_settings.jpg) ## **Check your connection to the service** **You need an active internet connection.** In this example, we are using the game Chrono Trigger (USA) with the Snes9x core. Launch the game and trigger the Quick Menu. Go to Achievements and you should see a list of the unlockable trophies for this game. ![](../image/retroarch/retroachievements/achievements_list.png) ## **Check your progress** On the retroachievements website, you can login and access your account page. You should be able to check your progress in the games and see which trophies you unlocked. Trophies unlocked in hardcore mode are marked with a special color. You can also check the progress of your friends and add comments on their trophies. ![](../image/retroarch/retroachievements/achievements_progress.png) ## **Cores Compatibility** For a list of supported cores, take a look at the [Emulator Support page on RetroAchievements](https://docs.retroachievements.org/general/emulator-support-and-issues.html). Cores that are not listed as supported are likely to have issues with achievement logic, and tickets from players using those can be closed without investigation. In the future, it is likely that unsupported cores will be blocked in hardcore mode, as well. ## **Troubleshooting FAQ** **Question:** RetroAchievements were working fine last time I played, but now it suddenly says I can't login! I haven't changed anything! **Answer:** Your login token may have expired, and you will need to generate a new one by clearing out your login information in **Settings > User > Accounts > RetroAchievements** and re-entering it. **Question:** I did whatever the achievement required, but it didn't award me the achievement! **Answer:** When offline, awarded achievement status is cached and will be awarded once you reconnect to the internet. This only applies to the current session, though, so make sure you don't quit out of RetroArch before reconnecting. If you've had a working internet connection and it still doesn't trigger, make sure you're using [an officially supported core](https://docs.retroachievements.org/general/emulator-support-and-issues.html) before requesting support. ================================================ FILE: docs/guides/retroarch-accessibility-guide.md ================================================ # Retroarch Getting Started guide for users of the accessibility mode ## Introduction This user guide is to aid users of screen readers who are newcomers to Retroarch begin using the program. Retroarch is an emulation front-end which allows one to play many games from many video game consoles, Arcades, and vintage computers. As of version 1.8.2, the user interface is accessible to blind people. Using the AI service within games, one is able to read textual content: menus, character dialog, statistics screens, ETC. Along with the game’s sound design, this makes many games which were playable even more enjoyable, or games which use only text playable at all. For now, accessibility mode works on Windows, macOS, and Linux operating systems. ## Retroarch Terminology - **Retroarch:** A front-end for many video game emulators. - **Front-end:** A program that brings multiple other programs into one universal interface. - **Core:** a video game console, game engine, or media player within Retroarch. - **content:** a video game, media file, or Homebrew program that can be loaded by a Retroarch core. - **accessibility:** In Retroarch, a setting which speaks the user interface of the program. - **AI service:** A service which takes a screenshot of a game and acts upon it based on the setting chosen in the AI service settings. In this guide, we’ll focus on Narrator mode. - **Netplay:** Playing an originally offline video game across the local network or Internet. - **bind:** To link one thing with another. In Retroarch terms, to link a key or button with an action. ## Download Retroarch To download Retroarch, go to [Retroarch's download page](https://www.retroarch.com/?page=platforms) and choose the download for your system. Windows users should choose the 64-bit installer version, unless they have an old computer with a 32-bit operating system. Mac users should download the version under the “Apple macOS / OSX” heading; iOS and tvOS users are encouraged to install from the App Store. Linux users should see if version 1.8.2 or higher is in their package manager, and get that and the cores through APT, Pacman, DNF, and so on, or compile it yourself. For Android and game consoles, accessibility features are not implemented. ## Open the Program After installing Retroarch, launch the program in the usual way according to your system. Right now, it will not speak, but if it opens, that means it’s at least installed correctly, and you can press escape twice to close it, or using the usual quit command of your operating system. ## Turn on accessibility To turn on the accessibility feature, do the following: - Open Retroarch. - Press **Left Arrow**, **Down Arrow**, then **Enter**. - Press **up arrow** seven times. - Press **Enter** twice, or **Enter** then **Right arrow**. - You’ll hear “Retroarch accessibility on.” Now, you can either keep exploring the menu, or quit and reopen Retroarch for a fresh start. Accessibility mode will stay on, and if not, after enabling accessibility, arrow left once, then down arrow until you hear "settings", then arrow down to configuration, press **Enter**, and enable “save on exit” with **enter**. **note**: in later versions of Retroarch, the default menu has been set to Ozone. For an easier experience, especially with gamepads, you may switch to the "XMB" menu by going to settings, drivers, menu driver, and changing "ozone" to "XMB." The rest of this guide assumes that you are using the XMB menu. ## Set Narrator Speed If you find that Retroarch is speaking too quickly or too slowly, you can change the speed. - From the Retroarch accessibility menu, press **Down arrow**. - Press the **Left arrow** to decrease the speed, and the **Right arrow** to increase it. ## Navigate the Interface The Retroarch user interface is composed of menus, dialog boxes, text-entry boxes, and so on. This does not include the games played using Retroarch. To navigate the interface, use the arrow keys to traverse menus, Enter to activate items, left and right arrow keys to adjust options, and backspace to go back to the previous menus. You can press the Shift key to get information on the currently focused menu item, and then Enter or Backspace to exit that dialog. There are two main navigation elements to be aware of in Retroarch’s user interface. Menus are vertical, so you use the Up and Down arrows to navigate these. Tabs, sometimes called Vertical menus, are navigated with the Left and Right arrows. Main Menu, Settings, Netplay, Favorites, ETC. are tabs, but Load Core, Load Content, and Quit are menu items. To the left of the Main Menu, you’ll find the “Horizontal Menus,” which are lists of game systems and games which you’ve played on that system. For example, if you play Play Station games, there will be a menu of those. The games in each tab are in a vertical list, but the other game systems, like PlayStation Portable, will be in another tab to the left of that. Tabs like Favorites, Netplay, and Settings are to the right of the Main Menu. ## AI Service The AI service is a retroarch feature which takes a screenshot of the game being played, and can either translate the text in the image, speak the text, or speak the text with the same voice as the Narrator used for the Retroarch user interface. You will have to configure the AI service yourself, linking it with a translator, and setting up a key for it. This can be useful for reading menus in games, unspoken character dialog, character dialog in another language, or other textual content, like instructions. Because the AI service uses Artificial Intelligence, the spoken text may not be completely accurate, as is all optical character recognition technology. If there is a table, it will be read one column at a time. ### How to Enable the AI Service From the Main menu, press **Right Arrow** to move to the Settings menu. There, press **Down Arrow** until you reach the AI Service item, and press **Enter** to open it. Here, you can choose which mode the AI service will be in: - **Image Mode:** The service will capture an image of text, translate it, and send it back to the screen as an image. - **Speech Mode:** The Service will grab an image of text in a game, translate it if needed, and speak it using a third-party text to speech engine. - **Narrator Mode:** The AI service will grab an image of text, translate it if necessary, and send it to Retroarch’s accessibility system to be spoken by your operating system’s speech synthesizer. For now, choose Narrator mode by pressing **Right Arrow** and down arrow to “Ai Service Enabled,” and if needed, turn it on with **Enter**. Also, while you’re here, you can set the language to translate, and to translate to. For example, if you primarily play Japanese games, but you prefer to hear your games spoken in Esperanto, assuming you have a voice for that language, set the source language to “Japanese,” and the target language to “Esperanto.” You can also leave the source language at “Don’t care,” and the Service will guess the language of the game. ### Sign up for ZTranslate To use the AI Service, you need to link it with an online translation service. The easiest method is to use ZTranslate. - In your web browser, go to - Find the “Sign Up” link, and press **Enter** on it. - Fill out the form, and submit it to make an account there. - Check your email, and verify the account by clicking the included link. - When logged in, go to the “Settings” link, and press **Enter**. - Move to the “Quota” heading, and arrow down to the “API key” section. - Copy the API key, and paste it into a Notepad, text edit, GEdit, Pluma, or Nano file. ### Configure the Service To configure the service, go to the Settings link on ZTranslate’s site, and find the OCR Page. There, you can set confidence levels, which tell the Service what level, from 0 to 1, of confidence to translate the text with. In the Profile page, you can set and change personal information. ### link Retroarch with your account To link Retroarch with your ZTranslate account, find your Retroarch configuration file. Find your Retroarch folder: - Open Retroarch - Right arrow to Settings - Down Arrow to directories - Press Enter - Find the configuration directory and note the path to it, then exit retroarch. Open the configuration directory, and then open Retroarch.cfg. There, change the line starting with \#+beginexample aiserviceurl = "=" \#+endexample Here, you can simply copy and paste the URL in quotes to your configuration file, replacing with your own key, getting rid of the less-than and greater-than signs. ### Bind a key to the AI Service Now, for easy access, we can bind the AI Service command to a key. To do this: - Go into retroarch’s settings menu. - Arrow down to Input and press **Enter**. - Arrow down to “hotkey binds,” and press **Enter**. - Arrow down to “AI Service,” and press **Enter** and quickly press the key, just once, that you’d like to bind to it. - Press **Up Arrow** then **Down Arrow** to read the key that AI Service is bound to, to make sure it’s what you want. - Press **Backspace** a few times to exit those menus. ## Use controllers Retroarch not only works with keyboards. One can, if their headphones have a long enough chord, or their controller has a headphone jack, play games, and use the AI Service, right from a game controller. Usually, all one has to do is plug in a controller, and retroarch automatically configures and works with it. Sometimes, though, Retroarch’s control mappings are not to the user’s liking, some some reconfiguration is in order. ### Map controls To map controls, go to the settings menu in Retroarch, arrow down to User one binds, press **Enter**, and down arrow to a button you want to configure. Press **Enter**, and then quickly press once the button you want the command, like “D-Pad Up,” to be mapped to. Repeat this with all other buttons, and press **Backspace** to exit that menu. # Bind Hotkeys You can also bind hotkeys. This is useful for binding commands, like AI Service, Rewind, or Fast Forward, to a controller button. To do this, go into the Settings menu, then “Input,” then “Hotkey Binds.” Arrow down to the command you’d like to configure a key for, press **Enter**, press a key on the keyboard or button on the controller, and it’ll be bound. # Download Cores In retroarch, cores are video game console emulators, game engines, video and picture viewers, or game music players. To download one, from the main menu, go to “load core,” and press **Enter**. Then, arrow down to “Download a core,” and press **Enter**. In this list, you’ll find a lot of cores which have year numbers or other differentiating words after it. These are alternatives, in case the main core, the one without year numbers or specifying words beside it, do not work. For example, if there is “PPSSPP,” and “PPSSPP 2019,” it is good to go with “PPSSPP” first. # Update Cores Cores, like many other programs, receive updates to make games run faster, more smoothly, or add compatibility with new games. Particularly, the “Play” core, which allows one to play PlayStation Two cores, will have future updates addressing speed and compatibility in many games, as it is a relatively new emulator. To check for updates, do the following: - In the Main Menu, arrow down to “online updater”. - Arrow down to “Update Installed cores,” and press **Enter**. # Load Content Now that we have cores, we can load content into them. Content can be a game, video file, picture, or game music file, depending on what core you use. Retroarch comes with Doom and Tomb Hunter open game engines, which are not yet accessible, but you can find enjoyable games for other systems that you can play using other cores. To load content, choose “Load Content” from the main menu, use the arrow keys and Enter to navigate directories to the game on your computer, and press **Enter** on the game file to open it. If you do not see the game file, download a core that can play that kind of game. Once you’ve pressed **Enter** on the game file, you’ll be presented with a list of cores that could open that type of file. Choose the right one for your game, and press **Enter**. The game will start, and you can begin having fun. ## Use The Quick Menu The Quick menu is a menu you can open within the game to customize controls, use Cheat Codes, save or load save states in the game, reset, or close the game. To open the Quick actions menu, press **F1**. To close it without making changes, press **Escape**. # Other gaming resources Other gaming resources for people who are blind include: - [The Audio Games site](https://audiogames.net) has a listing of accessible games and an active forum. - [AppleVis](https://www.applevis.com) has mobile game listings and a gaming forum. - [This project](https://github.com/devinprater/accessible-retro-games) is a voluntery listing of accessible retro games playable by the blind. ## Getting More Help If you run into an error in Retroarch itself, not cores or games, or a problem with the accessibility service, please check the [Retroarch Issues page](https://github.com/libretro/RetroArch/issues), and if you cannot find it, create a [Github account](https://github.com) and submit one of your own. If you’d like general help with using retroarch, join its [Discord server](https://www.retroarch.com/?page=discord) and ask your questions there. ================================================ FILE: docs/guides/retroarch-cloud-sync.md ================================================ # RetroArch Cloud Sync Cloud Sync enables seamless synchronization of configuration and save data to a cloud server, allowing you to keep multiple devices in sync. ## Supported Backends There are three cloud sync backends available: | Backend | Platforms | Notes | |---------|-----------|-------| | **WebDAV** | All | Requires server URL, username, and password | | **iCloud** | macOS, iOS, tvOS | Uses CloudKit (Apple's database service) | | **iCloud Drive** | macOS, iOS | Uses iCloud Drive file storage | ### WebDAV WebDAV is a standard protocol supported by many cloud providers and self-hosted solutions. You'll need: - A WebDAV server URL (e.g., `https://webdav.example.com/RetroArch/`) - Username and password ### iCloud vs iCloud Drive Both use your Apple iCloud account but work differently: - **iCloud** uses CloudKit, Apple's database service. Data is stored in a structured database format. - **iCloud Drive** stores files directly in iCloud Drive storage, similar to how other apps store documents. !!! note "iCloud Drive files are not visible in Files.app" Files synced via iCloud Drive are intentionally hidden from the Files app. This is by design—the sync system uses a manifest file to track file hashes, and direct editing of files would corrupt the sync state. Your data is safely stored in iCloud and syncs between devices, but you should only access it through RetroArch. ## What Gets Synced Cloud Sync can synchronize the following directories (each can be enabled/disabled individually): | Directory | Default | Contents | |-----------|---------|----------| | **Save Files & States** | On | Game saves (`.srm`) and save states | | **Configuration** | On | Core configs, core options, shader presets, MAME/FBNeo hiscores | | **Thumbnails** | Off | Custom thumbnails (use the thumbnail downloader for standard ones) | | **System Files** | Off | BIOS files, etc. (can be large; use with caution) | ### Excluded Files The following are automatically excluded from sync: - `retroarch.cfg` (main configuration file) - Playlist files (`content_*.lpl`) - `.DS_Store` files (macOS) ## Configuration ### Initial Setup (First Device) Start with your primary RetroArch device to establish the initial cloud state. 1. Navigate to **Settings → Saving → Cloud Sync** 2. Configure the following: | Setting | Description | |---------|-------------| | **Enable Cloud Sync** | Turn on to enable syncing | | **Destructive Cloud Sync** | When OFF, deleted/overwritten files are backed up locally | | **Cloud Sync Backend** | Select your backend (webdav, icloud, or icloud_drive) | | **Sync Saves** | Sync save files and save states | | **Sync Configs** | Sync configuration files | | **Sync Thumbnails** | Sync thumbnail images | | **Sync System** | Sync system/BIOS files | For WebDAV, also configure: | Setting | Description | |---------|-------------| | **Cloud Storage URL** | Your WebDAV server URL (include trailing slash) | | **Username** | WebDAV username | | **Password** | WebDAV password | 3. Save the configuration and restart RetroArch 4. The initial sync will begin automatically (watch the status line at the bottom) ### Adding Additional Devices Configure each additional device with identical settings. Pay special attention to these directory settings—they must match across all devices: - Sort Saves into Folders by Core Name - Sort Save States into Folders by Core Name - Sort Saves into Folders by Content Directory - Sort Save States into Folders by Content Directory !!! warning If these settings don't match, devices will store files in different locations and sync will fail to merge them correctly. ## How Cloud Sync Works Cloud Sync uses a three-way merge algorithm with two manifest files: 1. **Server Manifest** - Tracks what's stored in the cloud 2. **Local Manifest** - Tracks what was last synced from this device When sync runs, RetroArch compares: - Current local files - Local manifest (what we last synced) - Server manifest (what the cloud has) This allows the system to detect: - New local files → upload to cloud - New server files → download to device - Changed files → determine which version is newer - Deleted files → propagate deletion (or backup if non-destructive) - Conflicts → when both local and server changed the same file ### Sync Mode The **Sync Mode** setting controls when synchronization occurs: | Mode | Behavior | |------|----------| | **Automatic** (default) | Syncs on RetroArch startup and when cores are unloaded (returning to menu) | | **Manual** | Only syncs when you explicitly trigger it via **Sync Now** | In **Automatic** mode, sync also runs when RetroArch resumes from the background on iOS. Use **Manual** mode if you want full control over when sync happens, or if you're on a metered connection and want to minimize data usage. ### Sync Now The **Sync Now** option (in Settings → Saving → Cloud Sync) manually triggers a sync. This works in both Automatic and Manual modes, allowing you to force a sync at any time. !!! tip Always close the running content (Close Content) and return to RetroArch's main menu before quitting RetroArch. This ensures your latest saves are synced. Quitting RetroArch while content is still running may skip the sync. ### Conflict Resolution A conflict occurs when the same file is modified on multiple devices before they have a chance to sync. Specifically, a conflict is detected when: - The server version differs from what was last synced, AND - The local version also differs from what was last synced Another conflict scenario is when one device deletes a file while another device modifies it. **Current behavior:** When a conflict is detected, RetroArch does not overwrite either version. The local file remains unchanged, the server file remains unchanged, and the conflict is logged. The file is temporarily excluded from sync until manually resolved. **Identifying conflicts:** - The status line will show "Cloud Sync finished with conflicts" - The log file will contain entries like: `[CloudSync] Conflicting change of saves/game.srm` **Resolving conflicts manually:** 1. Enable debug logging and check the log to identify which files are conflicting 2. Decide which version you want to keep (local or server) 3. To keep the **server** version: delete or rename the local file, then let sync run again to download the server version 4. To keep the **local** version: edit the local manifest file (`manifest.local` in your downloads/core assets directory) and update the conflicting file's hash to match the server's hash. On the next sync, RetroArch will see the local file as changed and upload it !!! tip To avoid conflicts, try not to use RetroArch on multiple devices simultaneously. Always let sync complete on one device before starting a session on another. ### Non-Destructive Mode When **Destructive Cloud Sync** is OFF, files that would be deleted or overwritten are backed up to: ``` [core_assets_directory]/cloud_backups/[path]-YYMMDD-HHMMSS ``` This allows recovery if sync makes unwanted changes. ## Sync Status Sync progress is displayed in the bottom-left status line. Messages include: - "Cloud Sync in progress" - Sync is running - "Cloud Sync finished" - Completed successfully - "Cloud Sync finished with conflicts" - Completed but conflicts were detected - "Cloud Sync finished with failures" - Some operations failed - "Cloud Sync failed" - Could not connect to backend ## Troubleshooting ### Enable Logging 1. Go to **Settings → Logging** 2. Enable **Log to File** 3. Set **Logging Level** to **Debug** Cloud Sync logs detailed information prefixed with `[CloudSync]`. ### Common Issues **Sync not starting** - Verify Cloud Sync is enabled - Check network connectivity - For WebDAV: verify URL, username, and password - For iCloud: ensure you're signed into iCloud on the device **Files not syncing between devices** - Ensure directory organization settings match on all devices - Check that the same sync options (saves, configs, etc.) are enabled - Wait for sync to complete on one device before starting another **Conflicts appearing** - Avoid using multiple devices simultaneously - Always let sync complete before closing RetroArch - Check logs to identify which files are conflicting **iCloud Drive: "Can't see files in Files.app"** This is intentional. Files are stored in a private app container to protect sync integrity. Your data is syncing correctly even though it's not visible in Files.app. ================================================ FILE: docs/guides/rgui.md ================================================ # RGUI (GUI) **RGUI** is a simple built-in user interface for RetroArch. It was originally introduced in the Wii port of RetroArch. RGUI was later refitted for use on low-powered and/or low-resolution devices. ![RGUI startup screen](../image/retroarch/rgui/rgui.png) ## Features While RGUI cannot configure absolutely everything, it can do the most common things you would want to do while using RetroArch. - Selecting libretro core - Load a game - Tweak per-libretro core options (e.g. colorization in GameBoy) - Load game from history (previous games played) - Save/load savestates - Configure shaders - Configure aspect ratios - Configure integer scale - Toggle fullscreen - Swap disk images (needed for PlayStation, see notes below!) - Take screenshots - Enable/disable real-time rewind - Simple input configuration - Mute/unmute audio - Exit RetroArch ## Navigating the menus Regular input binds will apply, and binds here are defined in terms of the RetroPad, RetroArch's joypad abstraction. | Button | PC Default | Action | |--------|------------|--------| | **A button** | X/Return | Accept/OK | | **B button** | Z/Backspace | Back/Cancel | | **Select** | Right shift | Display tooltip | | **Up/Down D-pad** | Up/Down keys | Move up/down menus | | **Left/Right D-pad** | Left/Right keys | Toggle settings, or jump up/down menus | ### Searching through lists with keyboard When using a keyboard, it can be slow to navigate a large list using gamepad-like controls. To help this, you can type `/` (forward slash) at any time to bring up a search box. Type a search string and hit Return. The cursor should jump to the first entry that matches. The search will match mid-path strings: However, if a match is found at the beginning of the path (like when searching for the first letter), the start-of-path match will take priority. The forward slash is recognized on character basis, not on the key itself. This allows e.g. Norwegian layouts to type forward slash by pressing 'shift + 7'. Characters which are outside the ASCII set are recognized but ignored, as RGUI cannot render such characters anyway. ## Config file By default, RetroArch looks for a config in various places depending on OS: - **Linux/OSX**: `$XDG_CONFIG_HOME/retroarch/retroarch.cfg`, then `~/.config/retroarch/retroarch.cfg`, then `~/.retroarch.cfg`, and finally, as a fallback, `/etc/retroarch.cfg`. - **Windows**: `retroarch.cfg` in same folder as `retroarch.exe`, then `%APPDATA%\retroarch.cfg`. To override this, use `retroarch --config customconfig.cfg`. If you have some special options you want to store in separate config files you can use `retroarch --config baseconfig.cfg --appendconfig specialconfig.cfg`. See man-page and/or `--help` for detail. | Warning | |-------- | | While you are changing settings in runtime, they are not saved to disk afterwards on PC by default. If you want RetroArch to automatically write back the config, either set `config_save_on_exit = true` in config, or enable this under Settings -> Config Save On Exit from within RGUI. | By design, the config file is considered immutable as it is likely maintained by the user, and should not be overwritten behind the users back. This is not the case on consoles however, where looking at the config manually isn't really an option for most users. ### Configuring input Currently you can configure two settings per player (on PC): - **Device**: Picks which gamepad to use for player N. The name of the pad is available. - **Device Type**: Picks which device type to use. This is relevant for the libretro core itself, and mostly useful for PlayStation, which needs to know if you're using a DualAnalog device or not. #### Configuring controller input * Configuring controller input is supported from within RGUI. * Normal gameplay binds as well as RGUI hotkey binding is supported. It is possible to bind everything in succession for convenience. #### Configuring keyboard input Configuring keyboard input is currently not supported. To configure keyboard binds, it must be done outside RGUI. ### Thumbnails RGUI thumbnail support requires the use of playlist files and thumbnail image packs: See [ROMs, Playlists, and Thumbnails](../guides/roms-playlists-thumbnails/). To view existing playlists choose `Playlists` from the main menu or the `Load Content` menu. Select a playlist, and while browsing its contents use the RetroPad **Y button** (or **Spacebar** on PC) to toggle the full-screen thumbnail associated with the currently highlighted entry: *Thumbnails off:* ![Thumbnails off](../image/retroarch/rgui/thumbnails_off.png) *Thumbnails on:* ![Thumbnails on](../image/retroarch/rgui/thumbnails_fullscreen.png) Any thumbnail image larger than 320x240 will be downscaled automatically to fit the screen. Three downscaling methods are provided, allowing a choice between performance and quality. To switch between them, from the top menu select `Settings > User Interface > Appearance` and set the `Thumbnail Downscaling Method` option to one of: - **Nearest Neighbour (Fast)**: Simple (pixelated) nearest neighbour scaling. Has a very low impact on performance, and should be usable on any hardware. - **Bilinear**: Smooth (although potentially blurry) resampling. Slower than nearest neighbour, but should be usable on most hardware. - **Sinc/Lanczos3 (Slow)**: High quality resampling (although sometimes generates artefacts when source image contains dithering). May cause lag on very low end devices, but has no discernable performance impact on desktop-class hardware. Note that it is possible to display thumbnails on the right of a system's playlist: ![Thumbnails on](../image/retroarch/rgui/thumbnails_on.png) This option can be toggled on at `Settings > User Interface > Appearance> Show Playlist Thumbnails`. The options immediately below it, `Top Thumbnail` and `Bottom Thumbnail`, can be set to display: - Boxart - Title Screen - Screenshot ## Applying Shaders See the [shaders user guide](shaders.md). ## Themes The visual appearance of RGUI may altered by choosing one of 32 built-in color themes. These change both the color scheme and sometimes the background wallpaper. From the top menu select `Settings > User Interface > Appearance` and cycle through the various `Menu Color Theme` options: ![RGUI color theme example](../image/retroarch/rgui/rgui_color_theme.png) Setting `Menu Color Theme` to `Custom` allows for an even greater degree of personalisation via the use of custom menu theme presets. A number of examples are provided in the RetroArch assets package, which may be downloaded by selecting from the top menu `Online Updater > Update Assets`. To choose one of these examples, go to `Settings > User Interface > Appearance` and select the `Custom Menu Theme Preset` option. In the file browser that opens, navigate to the `rgui` directory and select a `.cfg` file. ![](../image/retroarch/rgui/rgui_custom_theme_preset.jpg) Icons are not supported by RGUI: It instead uses ASCII characters where possible. ### Creating custom menu theme presets A custom menu theme preset is a plain text configuration file (e.g. `my_theme.cfg`) with the following contents: rgui_entry_normal_color = "0xAARRGGBB" rgui_entry_hover_color = "0xAARRGGBB" rgui_title_color = "0xAARRGGBB" rgui_bg_dark_color = "0xAARRGGBB" rgui_bg_light_color = "0xAARRGGBB" rgui_border_dark_color = "0xAARRGGBB" rgui_border_light_color = "0xAARRGGBB" rgui_wallpaper = "wallpaper_file.png" - **rgui_entry_normal_color**: Specifies the color of all 'normal' text displayed in any list. - **rgui_entry_hover_color**: Specifies the color of the currently selected entry, along with the core name and clock displayed at the bottom of the screen. - **rgui_bg_dark/light_color**: Specifies the menu background color. Setting `rgui_bg_dark_color` and `rgui_bg_light_color` to different values creates a chequerboard effect. Also used for the background of message boxes, and the title text when displaying thumbnails. - **rgui_border_dark/light_color**: Specifies the color of the border 'frame' drawn around the perimeter of the menu. Setting `rgui_border_dark_color` and `rgui_border_light_color` to different values creates a chequerboard effect. Also used for the frame of message boxes. - **rgui_wallpaper**: The relative file path to an optional wallpaper image. If this entry is omitted or left empty, no wallpaper is used. #### Color selection All color values are given in 0xAARRGGBB 8-digit hex code format - i.e. the first two digits correspond to the alpha (transparency) value, while the remaining 6 are a normal [hex triplet](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet). For example: fully opaque red would correspond to `0xFFFF0000`; 50% transparent green would correspond (approximately) to `0x7F00FF00`. For maximum legibility, the alpha value for all text colors should be set to `FF` (fully opaque). For the background and border, setting partial transparency allows the currently loaded content to be seen 'through' the menu when opening it while running a game. Note, however, that setting partial transparency causes colors to appear darker than expected, so careful tuning of the [hex triplet](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet) values is required. Appropriate transparency values are as follows: - When creating a dark theme *without wallpaper*, the border/bg alpha component should be set to `C0`. - When creating a light theme *without wallpaper*, the border/bg alpha component should be set to `E0`. - When creating a theme *with wallpaper*, the border/bg alpha component should be set to `FF`. (This is because it is very difficult to create a semi-transparent wallpaper image with proper colors, and so it is most practical to make everything fully opaque when using wallpapers) #### Creating wallpaper images RGUI wallpapers must have the following properties: - A resolution of exactly 320x240. - A color depth of 4 bits per pixel. (This is not *strictly* required, but using an image with greater color depth will not produce expected results) Wallpapers should be generated in [PNG](https://en.wikipedia.org/wiki/Portable_Network_Graphics) format. To produce a suitable image, the user should first create a regular 320x240 [PNG](https://en.wikipedia.org/wiki/Portable_Network_Graphics) file via any means at their disposal. [Inkscape](https://inkscape.org/) users may find the following simple template beneficial: [rgui_wallpaper_template.svg](rgui_wallpaper_template.svg) Once the image is complete, it is necessary to reduce its color depth. This may be done via one of two methods: #### 1) Using pngquant (recommended): [pngquant](https://pngquant.org/) is a command-line utility for lossy compression of PNG files. It supports very high quality conversion of images to [indexed](https://en.wikipedia.org/wiki/Indexed_color) color, in a manner appropriate for *most* kinds of wallpaper. Download/compile/install the latest version, then use the following command to process a wallpaper source file: > pngquant --posterize=4 --force -o "WALLPAPER_NAME_indexed.png" "WALLPAPER_SOURCE.png" Open the output `WALLPAPER_NAME_indexed.png` file and check that colors/gradients appear correct. In most cases, the result will be agreeable. If odd 'speckles' are apparent, it may be necessary to adjust the colors in the source image (this is a black art, and beyond the scope of this document). If the image has unacceptable, uncorrectable dithering then the `WALLPAPER_NAME_indexed.png` file should be discarded, and the following alternate method used instead: #### 2) Using GIMP [GIMP](https://www.gimp.org/) is a well known image editor. In general it produces lower quality color reduction than [pngquant](https://pngquant.org/), but it can handle certain gradients and patterns that cause [pngquant](https://pngquant.org/) to stumble. Download/install the latest version, then: - Open the wallpaper source file. - From the menu, select `Image > Mode > Indexed...` - In the `Indexed Color Conversion` pop-up, select: - `Generate optimum palette` - `Maximum number of colors:` `16` - `Color dithering:` EITHER `Floyd-Steinberg (normal)` OR `Floyd-Steinberg (reduced color bleeding` (use whichever looks best, but the other options here will not work). - Press `Convert`. - Inspect the result. Some manual touch-up may be required. (If the image is disagreeable at this stage, then the wallpaper probably isn't going to work - so start over...) - If all is well, select from the menu `File > Export As...` and name the file `WALLPAPER_NAME_indexed.png` - In the `Export Image as PNG` pop-up, untick `Save color values from transparent pixels` and click `Export`. Whether [pngquant](https://pngquant.org/) or [GIMP](https://www.gimp.org/) is used to create `WALLPAPER_NAME_indexed.png`, a final stage of optimisation should be applied to generate a 'clean' output wallpaper. This can be done using [OptiPNG](http://optipng.sourceforge.net/). Download/compile/install the latest version, then run the following command: > optipng -o7 -strip=all -force -clobber -out `WALLPAPER_NAME.png` `WALLPAPER_NAME_indexed.png` Edit the custom menu theme preset configuration file such that `rgui_wallpaper` points to the resultant `WALLPAPER_NAME.png` image. Once appropriate text/background/border colors have been set, the theme is complete. ================================================ FILE: docs/guides/roms-playlists-thumbnails.md ================================================ # ROMs, Playlists, and Thumbnails ## Storing games and other content Game ROMs are the source media of the games that can be played using RetroArch cores. They can be actual dumps of read-only memory, tape/floppy/compact disc images, or some other format. The ROM files may be placed anywhere in the file system where RetroArch has access - note that some platforms (notably Android) are not able to browse the full storage. It is practical if the file browser start directory is configured to the directory where ROMs are stored. Many users sort their ROMs into subfolders named after the system which the ROMs belong to, which results in a folder arrangement such as: roms/ Atari - 2600/ Atari Game 1.zip Atari Game 2.zip Atari Game 3.zip Nintendo - Nintendo Entertainment System/ NES Game 1.zip Sega - 32X/ 32X Game 1.zip 32X Game 2.zip etc. etc. This arrangement is not required and you are free to organize your ROMs as you prefer. Also, as a general guideline, content from disc-based systems (Compact Disc images, etc.) should not be zipped for RetroArch use. ## Working with Playlists Playlists are the lists of games and other content that can be generated automatically by the RetroArch playlist scanner, generated by a third-party playlist utility or script, or edited by hand in a text editor. ### RetroArch Playlist Scanner RetroArch incorporates a ROM scanning system to automatically produce playlists. Each ROM that is scanned by the playlist generator is checked against a database of ROMs that are known to be good copies. In order for content to be correctly scanned, you must: - Have a compatible core already downloaded and installed (note: Scan Without Core Match setting removes this requirement) - Update `Core Info Files` via `Online Updater` - Update `Databases` via `Online Updater` - Restart RetroArch if any of the above was just done For a normal scan, the content must match existing databases from the [libretro-database README](https://github.com/libretro/libretro-database#retroarch-database). If those conditions are met but content is still not being added automatically to a playlist, consider submitting an issue report on [github](https://www.github.com/libretro/RetroArch/issues). There is an option to do manual scan, which does not require a database, and just needs the file names to match. Results from the manual scan will be playable (as long as the respective core supports them), but may lack thumbnails and do not appear in the Explore menu. ### Designating which core to use RetroArch will attempt to detect and use the correct core for use with the ROMs that are used as part of a playlist. Under some circumstances, it may be useful to manually set a particular core for one of its playlists. This can be accomplished within the Playlists submenu in the RetroArch settings. ## The Explore menu RetroArch provides an Explore menu which can be used for browsing all content that were added to playlists using any database attribute - release year, genre, etc. ## Thumbnails RetroArch can display three types of thumbnails (small still pictures) for games in playlists: * In-game snapshots * Title screen snapshots * Boxart ![An in-game snapshot displayed with a Sega - 32X playlist.](http://www.lakka.tv/doc/images/thumbnails.png "An in-game snapshot displayed with a Sega - 32X playlist.") Most menu drivers support displaying two pictures when browsing the playlist. Displayed thumbnail types can be configured system-wide and also per playlist. All menu drivers can display fullscreen thumbnails when pressing Start, and Y button (left) can be used to cycle between available pictures. Thumbnails can be retrieved in multiple ways: * **Playlist thumbnail downloader (recommended)**: under Online Updater menu, all available thumbnails can be downloaded for a playlist. RetroArch will connect to http://thumbnails.libretro.com and retrieve the available thumbnail. - _WARNING_: the Playlist Thumbnails Updater process will over-write [custom thumbnails](#custom-thumbnails) set by the user for any game that has an associated thumbnail on the server. * **Individual thumbnail downloader**: there is a Download Thumbnails option for each entry in playlists. For RetroArch version 1.17.0 or later, you may hit download up to 3 times to try the flexible matches. * **On-demand thumbnail downloader**: if the respective option is enabled, RetroArch will try to download each thumbnail as the playlist is browsed. For RetroArch versions 1.17.0 or later, you may try flicking back and forth between entries up to 3 times to try the flexible matches. By default, on-demand thumbnail downloader does not try to fetch thumbnails based on ROM name, enable Settings / Playlist / Use filenames for thumbnail matching options for that. Thumbnail packs are no longer available, use one of the above methods, or see [Custom Thumbnails](#custom-thumbnails) section below. ## Playlist File Format Details Each playlist is a plain text file with an extension of `.lpl`. RetroArch 1.7.5 and later uses a JSON playlist format, although the backwards compatibility remains for the deprecated "6-Line" playlist format. **Note:** The paths in playlist files need to use the correct 'slash' character for the user's platform. Linux, OS X, and Android systems including Lakka and LudOS require forward slashes `/`, while Windows and DOS systems require backslashes `\`. !!! Hint "Hint for Windows Users" The built-in Notepad editor cannot work with cross-platform text files such as RetroArch playlist files. Many users and developers recommend the free [Notepad++](https://notepad-plus-plus.org/) as a replacement although most alternative text editors will also work. ### JSON Playlist Format The following example is a single-entry MAME 2003-Plus playlist for [Alien Arena](https://www.arcade-museum.com/game_detail.php?game_id=6850) -- the silent version of this game is available through the RetroArch **Content Downloader** found in the **Online Updater** menu. The romset with the `label` **Alien Arena** is located at `path` being `C:\retroarch\downloads\alienar.zip`; note that the backslashes are doubled in JSON-formatted playlist entries so that the value of the `path` entry is `C:\\retroarch\\downloads\\alienar.zip`. The ROM's corresponding `db_name` is `MAME 2003-Plus.lpl` which tells the menu driver which ROM database to use for looking up the game's metadata, thumbnails and game-system-specific icon-type. Menu drivers which implement playlist icons will use it to display it next to the ROM's name. #### `MAME 2003-Plus.lpl` ```json { "version": "1.0", "items": [ { "path": "C:\\retroarch\\downloads\\alienar.zip", "label": "Alien Arena", "core_path": "DETECT", "core_name": "DETECT", "crc32": "01ACE2AB|crc", "db_name": "MAME 2003-Plus.lpl" } ] } ``` !!! Alert You can omit the CRC or Serial for a manually created playlist entry by using the word `DETECT` instead, although it may limit your ability to use netplay for this playlist entry. ### 6-Line Playlist Format (Deprecated) !!! Warning This playlist format is deprecated and may not always be supported by RetroArch in the future. New playlists should be created in the JSON format. **Each entry in a playlist must be composed of 6 lines:** #### `MAME 2003-Plus.lpl` ``` C:\retroarch\downloads\alienar.zip" Alien Arena /tmp/cores/mame2003_plus_libretro.so DETECT 01ACE2AB|crc MAME 2003-Plus.lpl ``` 1. The path to the ROM. This can either be an 'absolute' path or a path relative to the current working directory. 2. The display name (you can use any name here) 3. The path to the core, this libretro core will be used to launch the ROM. **You can use the word DETECT in place of the core path here. Once this is done you can set the core to be used for this playlist via the RetroArch GUI.** 4. The displayname of the core, not really useful, we keep it there because the history list is also using this format 5. CRC or Serial number for database and other matching purposes. **You can omit the CRC or Serial for a manually created playlist entry by using the word DETECT here instead, although it may limit your ability to use Netplay for this playlist entry.** 6. The name of the system playlist to which this ROM is associated for looking up database metadata and thumbnails. ## Creating custom playlists (cross-platform, cross-folders) The standard playlists in RetroArch are usually platform-specific, i.e. `Nintendo - Game Boy.lpl` or `Sony - PlayStation.lpl`. Maybe you want to create custom playlists not limited within game-platforms or ROM-folders, e.g. "Multiplayer Racing Games" or "Medieval Themed Games". `content_favorites.lpl` and `content_history.lpl` are examples of default playlists which have this cross-platform behavior. So study them as an example first. ### To create a custom playlist - Copy/merge content from platform-playlists files into a fresh playlist file inside `/playlists/` entitled `My Sorting Prefix - My Playlist Name.lpl`. - Be sure that the ROM entries follow the syntax as described in section: [JSON Playlist Format](#json-playlist-format). - The `db_name` attribute entry must be the ROM's corresponding `Exact Game Platform Playlists Name.lpl` (e.g. `Nintendo - Game Boy.lpl`) in order to be associated with the correct metadata and thumbnails. ### Customize how/where your playlists are shown - Name your playlist in the scheme `My Sorting Prefix - My Playlist Name.lpl` or just `My Playlist Name.lpl`. - To tweak how playlists are displayed (with or without prefix) and how they are sorted (by prefix or by main name): - Go to: Settings > Playlists - Set options **Truncate Playlist Names** and **Sort Playlists After Name Truncation** to your liking. ### How to set up custom playlists (Screenshots) ![](../image/retroarch/playlists/playlist-folder-with-lpl-files-and-relevant-settings.png) ![](../image/retroarch/playlists/playlists-in-ui-1a-in-custom-playlist.png) ![](../image/retroarch/playlists/playlists-in-ui-1a2-in-custom-playlist-entry-with-thumbnail.png) ![](../image/retroarch/playlists/playlists-in-ui-1a3-in-custom-playlist-entry-with-thumbnail.png) ![](../image/retroarch/playlists/playlists-in-ui-2-in-other-custom-playlist.png) ### Third-Party Applications Since playlists are managed in text-only JSON format, there are a few third-party applications to help manage your playlists. - [RetroArch Playlist Editor](https://www.marcrobledo.com/retroarch-playlist-editor/) ([Source](https://github.com/marcrobledo/retroarch-playlist-editor)) - [RetroArch Playlist Buddy](https://forums.libretro.com/t/retroarch-playlist-buddy-playlist-and-thumbnail-generation-app/8417) ([Source](https://github.com/markwkidd/ahk-retroarch-playlist-helpers)) ## Custom thumbnails Users can set a custom thumbnail (i.e. a thumbnail that is different from the one automatically provided by RetroArch) by following the process below. !!! Hint "Terminology Note: Game Name" The term _Game Name_ refers to the name displayed [within a playlist in RetroArch](#retroarch-playlist-scanner), _not_ to the filename of the underlying file on the computer or device. _Game Name_ in this document is synonymous with playlist item label, playlist entry, content name, game title. - __File & Filename__. Name a PNG image file with a base filename that matches a game title displayed in a playlist. _Example_: if the game name is `Q-Bert's Qubes (USA)`, the intended image file must be named `Q-Bert's Qubes (USA).png` _(See below for additional flexible name matching options.)_ - __Location.__ Place the PNG in the [correct folder](#thumbnail-folder-paths) for the relevant playlist. - __Use a compatible image type.__ In RetroArch versions later than 1.19.1, image formats other than PNG can be enabled (jpg, bmp, tga). - __Replace invalid characters.__ The thumbnail's base filename should exactly match the game's title displayed in the playlist with an important exception. The characters `` &*/:`<>?\| `` in playlisted game titles must be replaced with `_` in the corresponding thumbnail filename. **Flexible name matching.** RetroArch versions 1.17.0 or later will attempt up to 3 different match techniques to associate a playlist item with a [properly located](#thumbnail-folder-paths) local thumbnail image file, in the following order: 1. __ROM file name <-> .png file name match__. A ROM file `Q-Bert's Qubes (USA) (1983).a26` would receive the local thumbnail `Q-Bert's Qubes (USA) (1983).png` if it exists, regardless of how the game name appears in the RetroArch interface. 2. __Game name <-> .png file name match__. `Q*Bert's Qubes (USA)` in a playlist would receive the local thumbnail `Q_Bert's Qubes (USA).png` if it exists. `*` is an invalid character and must be replaced with `_` in the image filename. 3. __Short game name <-> .png file name match__. RetroArch looks for a local thumbnail named after a shortened form of the game name ignoring all text starting at the first round bracket, in other words ignoring informational tags like Region etc. `Q-Bert's Qubes (USA) (1983) (Parker Brothers) [h]` in a playlist would receive `Q-Bert's Qubes.png` if that local image file exists. ### Thumbnail folder paths Thumbnail image files must be stored in subfolders according to this structure: - `thumbnails` directory within Retroarch folder (or in different location configured by user via Settings > Directory > Thumbnails) - `Playlist Name` folder with the exact same name as the playlist, except without `.lpl` at the end. For example, `Atari - 2600` - `Named_Boxarts` subfolder for boxart/cover art - `Named_Snaps` subfolder for in-game snapshots - `Named_Titles` subfolder for in-game introductory title screens **Example** of a Windows path to a correctly set boxart folder: `RetroArch-Win64\thumbnails\Atari - 2600\Named_Boxarts` **Example** of correct thumbnail file setup for content named `Q*bert's Qubes (USA)` in a default Atari 2600 playlist: ``` thumbnails/ Atari - 2600/ Named_Boxarts/ Q_bert's Qubes (USA).png Named_Snaps/ Q_bert's Qubes (USA).png Named_Titles/ Q_bert's Qubes (USA).png ``` _Note the replacement of the playlist game name's `*` with `_` in the filenames, in accordance with invalid characters described above._ ## Contributing Thumbnails: How To Thumbnails (along with [documentation](https://docs.libretro.com/meta/how-to-contribute/)) are an area where users who are not experienced in programming can contribute to RetroArch and in a way that helps all users. If you are interested in: - adding a thumbnail that you see is missing - correcting a thumbnail that is inaccurate or mistaken - replacing an existing thumbnail with a more representative or more aesthetic image follow the steps below. ### Overview 1. Make an account on github.com 2. "Fork" (copy) a [libretro thumbnail repository](https://github.com/libretro-thumbnails/libretro-thumbnails) to your own working area in github 3. Make your image file changes to your copy of the project (aka your fork), while following [libretro thumbnail rules](https://github.com/libretro-thumbnails/libretro-thumbnails/blob/master/README.md) and the detailed guidelines below 4. Create a "Pull Request" to request that the official project members review your proposed changes in order to accept it into RetroArch ### Detailed Steps - __Fork the repository.__ Visit the github.com [libretro thumbnail repository](https://github.com/libretro-thumbnails/libretro-thumbnails) directory that you want to contribute to and click the fork button. You must fork it at the level of specific console. The Fork button won't appear if you're viewing a lower level folder in the respository like "boxart" or "snaps.” _Example_. If you are doing GBA thumbnail work you should fork [Nintendo_-_Game_Boy_Advance](https://github.com/libretro-thumbnails/Nintendo_-_Game_Boy_Advance/). - **Why "Fork" your own**? Every part RetroArch's code and materials are open and accessible on github for input from any public volunteer (via Pull Request), but only official admins have direct edit access. Forking means copying your own copy of the project to freely draft changes in your own separate work area. Later you’ll send your proposed changes to the official project. - _Warning_: You must visit and fork the _current_ github project for the libretro thumbnail repository, for example [this one for SNES](https://github.com/libretro-thumbnails/Nintendo_-_Super_Nintendo_Entertainment_System), not to be confused with the similar-looking [archived version](https://github.com/libretro/libretro-thumbnails) which is inactive. - Correct: https://github.com/libretro-thumbnails/ - Incorrect: https://github.com/libretro/libretro-thumbnails - __Add / Upload your new image file.__ When viewing a specific thumbnail type folder (e.g. Named_boxarts, Named_titles, Named_snaps) within *your fork* of the thumbnails repository, click the pulldown button (near top right) that says **Add file** to see 2 options: - +Create new File - Upload File. - __Choose "Upload File"__. Select your new chosen image file. In this stage you are uploading to your fork/branch of the project. - __Follow all guidelines for a proper contribution.__ - Your choice of image file should meet the libretro thumbnail [rules in the ReadMe](https://github.com/libretro-thumbnails/libretro-thumbnails/blob/master/README.md), e.g. width scaled down to 512px. - For snaps (in-game screenshots), choose a good clear artful image that shows the art, spirit, or action of the game in normal or ideal gameplay. For examples of well-chosen well-composed in-game screenshots, see the back-of-box images printed on officially published games. - Name your image file correctly. - If replacing an existing image, name your new image file exactly as the previous one to guarantee that it will be matched to the relevant game name in RetroArch. (Unless your contribution is to correct an erroneous filename that doesn't match the game name database.) - If uploading a new thumbnail that has no prior existing version, research the naming conventions of libretro and how the game is named in databases. Name the image file according to the game name that RetroArch assigns in the playlist. - Use the correct path. Choose the correct console system folder and thumbnail type folder in the repository. - __Commit.__ The "Commit" button will save your change to your copy of the repository. You should generally commit to your own _master_. - __Pull Request (PR)__. Look for the button or option for a Pull Request when you Commit, though you may wait until you have finalized multiple changes (commits) and then include them all in a single PR. A Pull Request means sending a request to the official members to take your contribution (i.e. merge your fork) into the RetroArch repository. Admins will review your proposed changes and decide whether to accept it. You will eventually see a confirmation that it was approved or a discussion message if changes are needed. It may take time (even weeks or months) before an admin is able to examine the request, so please be patient. - __Verify that your Pull Request is active and correct.__ For example, if you made a Pull Request to contribute a Gameboy thumbnail then you can [view the request publicly listed at the official repository](https://github.com/libretro-thumbnails/Nintendo_-_Game_Boy/pulls). - _Warning_: It is possible to accidentally send a Pull Request to yourself if you committed your changes to your sub-branch instead of your own _master_. If needed, approve your PR to yourself to merge your sub-branch changes to your master, then do a Pull Request from your master to the official Libretro master project. For clarity on github.com, you can hover on any abbreviated branch path label to see a pop-up of the full path label. __About "Syncing."__ Contribution work involves changing your copy of the project while other people may be changing the official repository _after_ you created your fork. Github provides options to keep both your copy ("downstream") and the official repository ("upstream") up-to-date with ongoing changes. If you make multiple changes within your fork, you can use the **Contribute button** > Open Pull Request to send all your changes as one PR. You can use the __Sync button__ button to update your fork with other people’s changes that have happened upstream. ### The Thumbnail Server RetroArch retrieves thumbnails from a server (https://thumbnails.libretro.com/) that is updated periodically with imports from the Libretro thumbnail repository on github. After a pull request is approved for a contribution, some time may pass before the updates are sent to the server. The final server update must occur before users will see new image contributions in RetroArch playlists. ## Custom icons/logos for playlist items RetroArch versions later than 1.19.1 include an option for the XMB menu driver to display custom per-game icons/logos in the playlist, instead of the default content icon, see [this example](https://github.com/libretro/RetroArch/pull/16758#issuecomment-2211771227). The required file format and subfolder structure follows the same pattern as [custom thumbnails](#custom-thumbnails): - Create a folder called `Named_Logos` alongside the `Named_Boxarts` thumbnail subfolder for the intended playlist - Put the logo image files there with base filenames that match the associated game's displayed name in the RetroArch playlist. **Limitations.** Logo support is only possible with XMB menu driver. The online thumbnail repositories do not contain logo collections. ================================================ FILE: docs/guides/rpi.md ================================================ The simple and optimized way to run RetroArch on Raspberry Pi is [Lakka](https://lakka.tv). However, if you already have a working Linux distribution on a Raspberry Pi, and just want to add RetroArch to it, that is also possible. ## Installing from distribution repositories Several repositories carry RetroArch for the armhf/aarch64 architecture used by the RPi models. Some issues that can be encountered when using these: - RetroArch version may be old - Binary may be too generic and not optimized for the actual model - Package may be set up to not allow core downloads But there is no harm in trying it. Use the system package manager (apt, yum or similar) to install `retroarch`. ## Compiling from source ### Major hardware and software variables A RetroArch binary on Raspberry Pi may be created in several flavors. The major factors are: - 32/64 bit OS. Only Pi 3 and 4 have a choice, older models can only use 32 bit OS. RetroArch can be compiled for both. - legacy or open source GL drivers (64-bit and Pi 4 does not have a choice). This can be set in `raspi-config`. Open source drivers (mesa) are recommended, see later for the legacy driver instructions. - GUI environment (X11 or Wayland) or special terminal based setup (KMS). Distributions that have no windowing environment, such as the "lite" versions of Raspberry Pi OS, may still run RetroArch using [KMS mode](../kms-mode). - audio driver in use: alsa or PulseAudio. If `pactl list cards` produces a list of sound devices, PA is in use, otherwise use alsa. - GPU memory: while it has no effect on compilation, at least 128 MB is recommended for Pi 0..3, for Pi 4 the default 76 MB is OK. ## Installing necessary packages for compilation Preinstalled packages may vary between distribution and releases. List is given using Raspberry Pi OS (Debian Bullseye). - base packages needed for all described compilations: `sudo apt install -y build-essential libudev-dev libegl-dev libgles-dev libx11-xcb-dev` - sound driver for PulseAudio, if it is in use: `sudo apt install -y libpulse-dev` - sound driver for alsa, if PulseAudio is not used: `sudo apt install -y libasound2-dev` (there is no harm in installing both audio libraries) - vulkan driver for Pi 4: `sudo apt install -y libvulkan-dev mesa-vulkan-drivers` - additional packages for KMS build: `sudo apt install -y libavcodec-dev libavdevice-dev libavformat-dev libavresample-dev libdrm-common libdrm-dev libdrm2 libegl1-mesa-dev libfreetype6-dev libgbm-dev libgbm-dev libgbm1 libgles2 libgles2-mesa libgles2-mesa-dev libsdl-image1.2-dev libsdl2-dev libswresample-dev libswscale-dev libv4l-dev libxkbcommon-dev libxml2-dev yasm zlib1g-dev` ## Retrieving RetroArch code RetroArch can be retrieved from Git (it may be needed to install git: `sudo apt install git`): git clone https://github.com/libretro/RetroArch -b v1.15.0 cd RetroArch or alternatively, just downloaded as a specific version (somewhat faster, but can not be easily updated and recompiled): wget https://github.com/libretro/RetroArch/archive/refs/tags/v1.15.0.tar.gz tar xvfz v1.15.0.tar.gz cd RetroArch-1.15.0 ## Configuration options Configuration for RPi 0..3 32-bit, disabling the legacy GL driver, GL1 support, enabling OpenGL ES instead of OpenGL, and adding support for the floating point unit found in all Pi's: ./configure --disable-videocore --disable-opengl1 --enable-opengles --enable-floathard Configuration for RPi 3 64-bit, where the floating point unit is default: ./configure --disable-videocore --disable-opengl1 --enable-opengles Configuration for RPi 4, adding OpenGL ES 3.1 support: ./configure --disable-videocore --disable-opengl1 --enable-opengles --enable-opengles3 --enable-opengles3_1 Several options can be added as a doublecheck. If the necessary libraries are installed, these are picked up automatically, adding the option ensures that missing libraries can not go unnoticed. - `--enable-pulse` for PulseAudio sound driver - `--enable-alsa` for ALSA sound driver - `--enable-udev` for udev input/joypad driver - `--enable-ssl` for SSL connection (for downloading via https) - `--enable-vulkan` for Vulkan video driver (usable on Pi 4 only) - `--enable-kms` and `--enable-egl` for libraries necessary for KMS mode In case of RPi 2 and 3 with 32-bit OS, NEON support can be explicitly enabled, by adding `CFLAGS='-mfpu=neon'` in front of `./configure` and `--enable-neon` to the options. In RetroArch, this has effect on the audio resampling algorithm compilation. In all platforms, code optimization can be triggered by adding adding `CFLAGS='-march=native'` in front of .configure. This also means resulting binary may not be executable on an other Pi model. ## Compiling and first updates Compilation is done with make command. In case of Pi 2 and later, compilation can be made faster by using 2 threads (-j 2). Using more than 2 threads is only recommended on Pi4 with 4GB or more RAM, as compilation of certain parts can eat up available memory and crawl system to a halt. make -j2 Compiling depends on SD card access speed as well. On a Pi 1, it can take two hours, on Pi 2, around 30 min, Pi 4 can finish under 10 minutes. RetroArch can be also installed to the default location, which is usually not writable without sudo: sudo make install Start RetroArch with logging enabled (`./retroarch -v`) to catch any potential problems, and carry out initial updates in the Online Updater: - download assets - download core info files - download controller profiles - download shaders In some cases, it may happen that input driver is not found and RetroArch will not start. In this case, add following line into `~/.config/retroarch/retroarch.cfg`, which at this point is almost empty: input_driver = "udev" ## Downloading or compiling cores Libretro cores are built automatically for most platform, but for `armhf` (all Pi 32-bit) or `armv7-neon-hf` (Pi 2 onwards 32-bit), there are only some quite old versions on libretro buildbot. For `aarch64` (Pi 3 and 4 64-bit), there is none. Building cores can be tried using libretro-super scripts. It is not guaranteed that all cores can be compiled for these platforms, as it depends on the core itself. Example with vitaquake2 core: git clone https://github.com/libretro/libretro-super cd libretro-super ./libretro-fetch.sh vitaquake2 ./libretro-build.sh vitaquake2 cp dist/unix/*.so ~/.config/retroarch/cores ## Further RetroArch settings It is worth to check if the audio driver matches the one you want. Threaded video setting may be enabled for speed enhancement. In KMS mode, the resolution setting is not exposed in the GUI if Vulkan is used, but it can still be modified. Edit following entries in `retroarch.cfg`, example for 1920x1080 50Hz: video_fullscreen = "true" video_fullscreen_x = "1920" video_fullscreen_y = "1080" video_windowed_fullscreen = "false" video_refresh_rate = "50.0" For Pi 4 to enable 4K 60 Hz refresh, a line is needed in `config.txt`: hdmi_enable_4kp60=1 [LED driver](../led-drivers/#sysled-driver) may also be enabled. ## Legacy GL drivers and dispmanx Initially, RPi's VideoCore IV GPU (used for models earlier than RPi 4) was supported through vendor-specific Broadcom OpenGL/EGL libraries. This library is linked when `--enable-videocore` option is specified for `./configure`. To compile RetroArch with legacy drivers, specify the `--enable-videcore` option instead of `--disable-videocore` above. Note that this library is only available for 32-bit systems. The binaries must be present in `/opt/vc` for compilation to work. Legacy drivers (or "userland") may be installed as `libraspberrypi-dev` package, or retrieved from https://github.com/raspberrypi/userland, and installed as: sudo apt install cmake git clone https://github.com/raspberrypi/userland.git cd userland/ ./buildme / To start RetroArch built this way, system must be switched to "Legacy GL" driver using `raspi-config`. This is not possible starting from Debian 12 Bookworm, so make sure you are running an older distribution. In addition to this, RetroArch has a specific `dispmanx` video driver that utilizes the vendor-specific API instead of OpenGL. This video driver can be enabled with `--enable-dispmanx`, however it has only limited functionalities, in particular only RGUI is supported, and there are no widgets/overlays. As a corner case, dispmanx driver works in fake KMS mode. Neither dispmanx driver nor legacy GL drivers work with RetroArch in KMS mode. If you run into problems with compilation, try adding the userland to package-cfg by issuing `export PKG_CONFIG_PATH=/opt/vc/lib/pkgconfig/` before running `./configure`. ## Checking OpenGL details Active GL driver can be checked by running `lsmod | grep vc4`. If this shows a loaded module, then the open source GL driver is in use. OpenGL performance can be checked with `glxgears` command: vblank_mode=0 glxgears -info This command should display a window with spinning gears, and an FPS counter in the command line. Few hundred FPS is expected (even on RPi 1), since vblank_mode=0 will decouple refresh from the display refresh rate. If glxgears can not be found, install `mesa-utils` package. If weird textures appear, you are running the legacy GL driver. If image is correct, but performance is low, check if the renderer has fallen back to software (LLVMpipe). In this case, run `raspi-config` and enable Glamor for acceleration. Pi 0..3 supports OpenGL ES 2, Pi 4 supports OpenGL ES 3.1. To doublecheck the supported versions, use `glxinfo | grep version`. ## Some tests in 2023 Tests were done as follows: - fresh installation of 2023-02-21 versions of Raspberry Pi OS - download, configure and build RetroArch 1.15.0 - keep default settings of RA, download assets and core info files - run RA in the native monitor resolution (fullscreen, 1920x1080x60hz) - no shaders - Pi4 is also tested with 4kp60 FPS of Ozone menu, after downloading assets, gl driver: | Setup | RPi 1 | RPi 2 | RPi 3 | RPi 4 | RPi 4 4K | |-------------------------------|:---------:|:---------:|:---------:|:---------:|:---------:| | Bullseye 32-bit, Mesa | ~5 | ~23 | ~29 | ~50 | ¬10 | | Bullseye 64-bit, Mesa | - | - | ~25 | ~55 | ¬13 | | Bullseye lite 32-bit, Mesa/KMS| ~20 | ~42 | ~50 | ~55 | ~26 | | Bullseye lite 64-bit, Mesa/KMS| - | - | ~48 | ~55 | ~23 | | Buster 32-bit, legacy | ~6/21 | ~9/40 | ~10/42 | - | - | On Pi 4, where there is a choice of gl, glcore and vulkan drivers, both glcore and vulkan gave an increase of a few fps in the menu. With legacy drivers, Ozone is much slower than XMB, so XMB values are also given. With Mesa, there is not much difference. FPS of VitaQuake2, default demo, default internal resolution (960x544), gl driver: | Setup | RPi 1 | RPi 2 | RPi 3 | RPi 4 | RPi 4 4K | |-------------------------------|:---------:|:---------:|:---------:|:---------:|:---------:| | Bullseye 32-bit, Mesa | <1 | ~12 | ~15 | ~52 | ~25 | | Bullseye 64-bit, Mesa | - | - | ~23 | >60 | ~26 | | Bullseye lite 32-bit, Mesa/KMS| ~3 | ~16 | ~25 | >60 | ~40 | | Bullseye lite 64-bit, Mesa/KMS| - | - | ~29 | >60 | ~45-50 | | Buster 32-bit, legacy | ~2 | ~13 | ~19 | - | - | ## Problems experienced Following problems were experienced while writing this guide: - KMS mode: Vulkan with KMS does not work in Bullseye. This is due to Mesa version being too old for the necessary KHR_display extension (added in version 21). - KMS mode: Display can become shifted (even the menu) in some configurations. - KMS mode: VC4 driver is needed for RetroArch, but some distributions (like Ubuntu Server) do not include necessary `dtoverlay=vc4-kms-v3d` line in `config.txt` by default. - On Buster, the terminal that is used to launch RetroArch, will continue to receive keypresses - Compiling for Pi4 needs all 3 of the opengles command line switches, even though they seem redundant ================================================ FILE: docs/guides/runahead.md ================================================ # RetroArch Run Ahead Every game has a certain built-in amount of lag, some react on the next displayed frame, some can take 2, 3 or even more frames before an action on the gamepad finally get rendered on screen. The Run Ahead feature calculates the frames as fast as possible in the background to "rollback" the action as close as possible to the input command requested. That feature deals with "internal" game logic lag. This means you can still take advantage of other RetroArch lag reduction methods that happens later, such as Hard GPU Sync or Frame Delay. It's located in **Quickmenu > Latency** (also in Settings > Latency). ## How many frames to Run Ahead? We need to find **the shortest internal input lag** a game can have, it's usually just moving the character: - Pause emulation (press "P" hotkey on keyboard). - Press and hold a direction on the controller. - Advance emulation frame by frame (press "K" hotkey on keyboard) until the character moves. At best an action will be visible on the next frame, so the frames of lag are **the amount of time you pushed "K" minus 1**. If you did select an higher number than needed, you will see a stutter/rollback when pushing buttons and possibly various weirdness. If you selected a lower number, repeating the test above will take more than 1 push on the "K" hotkey to see your character move. ## Can I always use Run Ahead? **Run Ahead relies on save states** so they need to be clean and fast enough. If a core doesn't support them, this can not work. Using **Second Instance** mode works around some save states limitation, use it if possible. Calculating several frames in advance means that your machine must be fast enough to run the core at that level of speed. **The higher the number of frames you are going to run ahead of emulation, the higher demands it places on your CPU.** ## More detailed explanation Here is a more detailed explanation on runahead by its author Dwedit. How the Run-Ahead feature currently works: There are two modes of operation. - Single-Instance Mode - Two-Instance Mode In Single-Instance mode, when it wants to run a frame, instead it does this: - Disable audio and video, run a frame, Save State - Run additional frames with audio and video disabled if we want to run ahead more than one frame - Enable audio and video and run the frame we want to see - Load State All save states and load states are done to ram and never reach the disk. In Two-Instance mode, it does this: - Primary core does Audio only, then saves state - Secondary core loads state, runs frames ahead discarding audio and video, then runs a frame with video only. For performance reasons, it only resyncs the secondary core when input is dirty, otherwise it keeps running additional frames on the secondary core while the input is clean. Why bother with Two-Instance mode at all? Many of the cores do not leave audio emulation in a clean state after loading state, so you would get buzzing. Using Two-Instance mode makes the primary core not do any load states and avoids that. In Single-Instance mode, it is possible to improve performance further by running ahead without loading state while input is clean, but I am not currently doing that. I'd imagine there would be issues if calling the "run a frame" function left you in a state further along than a single frame. I'm also not doing any speculative inputs at all. ================================================ FILE: docs/guides/shaders.md ================================================ ## Shader Presets Shader Presets are combinations of one or more shaders. They can be loaded via `Quick Menu -> Shaders -> Load Shader Preset` and if you want to keep the shader between play sessions, you can save them as an "automatic" preset via `Quick Menu -> Shaders -> Save -> Save Global/Core/Content Directory/Game Preset`. Global presets are automatically applied in any content for any core, while the Core presets are applied in any content for that specific core. Content Directory presets apply to all content in a certain folder and Game presets apply just to one game. Note that content directory and game presets are also core specific. If more than one automatic presets exist that could be applied, the most specific one wins out, so for example, if both a global and a game preset exists, the game preset will be used. You can also save other shader presets via `Quick Menu -> Shaders -> Save -> Save Shader Preset As`, so if you create your "perfect" combination of shaders you can recall this at any time with `Load Shader Preset` then continue on to save it as an automatic preset. This will save time if using the same preset for multiple games or cores. By default automatic presets will save to the retroarch config directory E.G. `/config/"name-of-core"/"name-of-core/directory/"game".slangp|glslp|cgp` or `/config/global.slangp|glslp|cgp` Presets saved with save as are saved in the base `shaders` directory. The shader directory can be changed via `Settings -> Directory -> Video Shader`. There are plenty of user created presets that come bundled with the RetroArch installation and these can be updated from `Main Menu -> Online Updater -> Update Slang|Glsl|Cg Shaders` *(You can find these presets in the shaders_glsl, shaders_slang, or shaders_cg subfolders of your shaders directory.)* [Example Screenshots](../shader/introduction.md) --- ## Editing Shader Parameters You can edit shader presets or build your own using these tools: - **Shader Parameters**: Shows the list of all tweakable shader parameters, which are previewed live. If you save a **Simple Preset** all these changes can be saved without changing the shader chain ## Editing the Shader Chain The Shader Chain which is a stack of shader passes each one pointing to a specific shader file. All Changes to the shader chain will force a **Full Preset** to be saved even if you have chosen to save a **Simple Preset** - **Prepend** - Prepend Preset adds a preset you choose before the currently loaded shader chain - **Append** - Append Preset adds a preset you choose after the currently loaded shader chain - **Shader Passes**: The number of shader passes to use. - For every **Shader Pass** you can configure: - **Shader #N**: Path to a shader. - All shaders must be of the same type (i.e. .glsl, .slang, or .cg). - **Shader #N Filter**: Hardware filter used for scaling. - **Don't Care** uses `Settings -> Video -> Bilinear Scale`. - **Shader #N Scale**: Scale for this pass. - The scale factor accumulates, i.e. 2x for first pass and 2x for second pass will give you a 4x total scale. - The last pass in the chain then is stretched to fullscreen using the `Settings -> Video -> Bilinear Scale` filter setting. - "Don't Care" uses **source** scale mode at 1x which means this pass will have the same resolution as the previous pass. - If the pass uses scaling methods which are not simple, (i.e. source scaling, different scaling factor for X/Y), the scaling factors can’t be displayed in the UI so the value shown may not be correct. - **Apply Changes**: You must use this to rebuild the shader chain to see your changes after adjusting any settings in the shader passes or the number of passes with **Shader Passes**. --- ## Simple Presets vs Full Presets There are two different kind of presets, a **Simple Preset**, and a **Full Preset**. a **Simple Preset** uses the `#reference` directive to reference an existing preset and apply parameter and texture path adjustments to it without affecting the original preset. A **Full Preset** is complete independent preset which includes all the passes and defines the **Shader Chain** used. If the original preset a **Simple Preset** is referencing changes, the changes will be inherited. Conversely the **Full Preset** is completely independent from all other presets. --- ## Simple Presets A **Simple Preset** uses a `#reference ""` directive, which when loaded acts as if the preset with the given path was loaded, after this any parameter values and texture paths are applied on top, overriding the existing values. There is also a possibility to have a chain of presets, each preset a referencing another. The last `#reference ` needs to point to a full preset (one which has the definition of all the passes and required textures) From the shader menu you can create a **Simple Preset** by loading any shader preset, making changes to the shader parameters then saving the preset with the `Quick Menu -> Save -> Simple Presets` option set to `ON`. Only the shader parameter changes you made will be saved as values inside the simple preset. When the simple preset is loaded these values will be applied on top of the values from the original preset referred to in the `#reference` line. If you make any changes to the **Shader Chain** like using **Prepend**, **Append**, or changing settings on any of the passes, a **Full Preset** will be saved instead which will include a full copy of all the passes and textures. Note that if a **Simple Preset** has been automatically loaded (Global, Core, Content Directory, Game Preset) and is then saved again the `#reference` path will point to the path specified inside the automatically loaded preset rather than at the automatically loaded preset itself. **Simple Preset Special Cases when Saving** - **Saving Over the loaded Preset:** - E.G. there are presets Preset_A, Preset_B, Preset_B references Preset_A. Preset_B is loaded then the user chooses to save over top of Preset_B. The reference to Preset_A is used instead of creating a a new reference to Preset_B which would be a cyclical reference. All current parameter values which differ from Preset_A will all be saved. - **Saving Over the preset referenced by the loaded preset:** - E.G. there are presets Preset_A, Preset_B and Preset_C, Preset_C references Preset_B which references Preset_A. The user loads Preset_C then saves over of Preset_B. The reference path to Preset A will be used to avoid a cyclical reference chain. All current parameter values which differ from Preset_A will all be saved. - **Saving Over a preset further up the chain:** - E.G. there are presets Preset_A, Preset_B, Preset_C and Preset_D. Preset_D references Preset_C which references Preset_B which references Preset_A. The user loads Preset_C then saves over of Preset_A. A full preset will be saved with all the passes and parameter values to avoid a cyclical reference chain. --- ## Advanced Referencing and .params files - A `Simple Preset` can/must include **one and only one** reference to a `Full Preset` or a chain terminating in a full preset. If you have references to more than one Full preset this will be considered an error and the preset will not load. - A simple preset can also include 0 or more references to `.params` files. - A `.params` file only includes parameter values and texture paths as well as references to other `.params` files. - Parameter value and texture paths in the reference chain are evaluated backward from the end of the chain, so the `.params` #references and parameter and texture values you see at the end of the chain will be applied last. --- ## Paths in Shader Presets Paths can be specified as relative paths or abbreviated root paths **Abbreviated Root Path Format** E.G. - `:/shaders/shaders_slang/stock.slang` - `:/` stands for the root of the Retroarch folder **Relative Format** E.G. - `shaders_slang/stock.slang` - This path corresponds to the path to stock.slang relative to a preset which is saved in the shaders folder When a shader preset is saved all paths will be automatically saved in whichever format creates the path with least directory depth. --- ## Wildcard Path Replacement Preset Wildcard Path replacement allows you to have fewer presets while addressing many scenarios by changing paths in response to the retroarch state when the preset is loaded. An example would be having one preset which could be used with the entire list of images from the Bezel Project. When a preset loads, text wildcards which are found in paths inside the presets will be replaced with values coming from the current RetroArch context. The replacement will be executed on both texture paths and reference paths, one or more wildcards can be placed in the filenames or paths. If no wildcards are found within the path, or the new path after replacing the wildcards does not exist on disk, the path will be left as it was before any replacement. Note: This replacement only happens only on preset load. If any retroarch context has changed since the preset was loaded the preset will need to be reloaded to react to this change. You can see real-time logging, including info from the wildcard replacement, live in Retroarch by turning on logging and turn off log to file. This causes an additional text window to appear when launching Retroarch. --- Example 1 - Have one preset show a different image for each game - `/shaders/MyBackground_$GAME$.png` if you were playing Ms. Pacman it would be replaced with: - `/shaders/MyBackground_mspacman.png` If no file (image or preset file) is found at the new path with the replacements, we revert to the original path. If there is no file at this path the shader will fail to load. - `/shaders/MyBackground_$GAME$.png` --- Example 2 - Have one preset show a specific image for all games who's ROMs are in the same folder - `/shaders/MyBackground_$CONTENT-DIR$.png` if your games were in a `MyVerticalGames` directory it would be replaced with: - `/shaders/MyBackground_MyVerticalGames.png` If no file found at the new path with the replacements, we revert to the original path. If there is no file at this path the shader will fail to load. - `/shaders/MyBackground_$CONTENT-DIR$.png` --- Example 3: - `/shaders/MyBackground_$VID-DRV$_$CORE$.png` If you were playing a Saturn game on the YabaSanshiro core it would be replaced with - `/shaders/MyBackground_glcore_YabaSanshiro.png` If no file found at the new path with the replacements, we revert to the original path. If there is no file at this path the shader will fail to load. - `/shaders/MyBackground_$VID-DRV$_$CORE$.png` ----- --- ## Possible wildcards/tokens to be replaced: --- `$CONTENT-DIR$` -> Content Directory of the game rom --- `$CORE$` -> Core name --- `$GAME$` -> Game file's name, E.G. ROM name --- `$VID-DRV$` -> Video Driver: Currently active driver, possible replacement values: * `glcore` * `gl` * `vulkan` * `d3d11` * `d3d9_hlsl` * `N/A` --- `$VID-DRV-SHADER-EXT$` -> Video Driver Shader File Extension: The extension of shaders type supported by the current video driver: * `cg` * `glsl` * `slang` --- `$VID-DRV-PRESET-EXT$` -> Video Driver Preset File Extension: The extension of shaders type supported by the current video driver: * `cgp` * `glslp` * `slangp` --- `$CORE-REQ-ROT$` -> Core Requested Rotation: Rotation the core is requesting, possible replacement values: * `CORE-REQ-ROT-0` * `CORE-REQ-ROT-90` * `CORE-REQ-ROT-180` * `CORE-REQ-ROT-270` --- `$VID-ALLOW-CORE-ROT$` -> Video Allow Core Rotation: Reflects Retroarch's setting allowing the core requested rotation to affect the final rotation: * `VID-ALLOW-CORE-ROT-OFF` * `VID-ALLOW-CORE-ROT-ON` --- `$VID-USER-ROT$` -> Video User Rotation: Rotation the core is requesting, possible replacement values, does not affect the UI: * `VID-USER-ROT-0` * `VID-USER-ROT-90` * `VID-USER-ROT-180` * `VID-USER-ROT-270` --- `$VID-FINAL-ROT$` -> Video Final Rotation: Rotation which is the sum of the user rotation and the core rotation if it has been allowed, does not affect the UI: * `VID-FINAL-ROT-0` * `VID-FINAL-ROT-90` * `VID-FINAL-ROT-180` * `VID-FINAL-ROT-270` --- `$SCREEN-ORIENT$` -> Screen Orientation: User adjusted screen orientation, will change windows from landscape to portrait, including the Retroarch UI: * `SCREEN-ORIENT-0` * `SCREEN-ORIENT-90` * `SCREEN-ORIENT-180` * `SCREEN-ORIENT-270` --- `$VIEW-ASPECT-ORIENT$` -> Viewport Aspect Orientation: Orientation of the aspect ratio of the RetroArch viewport * `VIEW-ASPECT-ORIENT-HORZ` * `VIEW-ASPECT-ORIENT-VERT` --- `$CORE-ASPECT-ORIENT$` -> Core Aspect Orientation: Orientation of the aspect ratio requested by the core * `CORE-ASPECT-ORIENT-HORZ` * `CORE-ASPECT-ORIENT-VERT` --- `$PRESET_DIR$` -> Preset directory's name --- `$PRESET$` -> Preset's name --- ## Command Line The `--set-shader` command line option allows to set shaders directly, bypassing even automatic shader presets. Example use: retroarch --set-shader "D:\RetroArch\shaders\shaders_glsl\blurs\kawase_blur_5pass.glslp" -L The shader path can be relative to the shader directory: retroarch --set-shader "shaders_glsl\blurs\kawase_blur_5pass.glslp" -L An empty parameter effectively disables any automatic presets: retroarch --set-shader "" -L ### Converting Cg shaders to GLSL In some cases, Cg shaders cannot be supported. This goes for OpenGL ES drivers, and when EGL OpenGL contexts are used (KMS mode for instance). Using Nvidia's `cgc` compiler, you can convert Cg shaders to GLSL shaders with the `cg2glsl` tool developed by us [here](https://github.com/Themaister/RetroArch/blob/master/tools/cg2glsl.py). It can convert single shaders as well as whole folder structures in batch. 100% compatibility is not guaranteed, but almost all shaders should work fine. Cg presets (.cgp) are not converted at the moment, but converting them is as simple as copying over the .cgp, renaming it to .glslp, and replacing references to .cg files to .glsl. ================================================ FILE: docs/guides/softpatching.md ================================================ # Softpatching ROMs with RetroArch RetroArch currently supports the UPS, IPS, BPS, and XDelta[^1] patching formats. If you load `rom.bin` and one of the following is present, the ROM will be autopatched: `rom.ups`, `rom.ips` or `rom.bps`. Autopatching only takes place if the libretro implementation supports loading ROMs from memory. You can apply multiple patches to one ROM by naming the patches with the `.ips$` extension, where `$` is a number. For example, given the following files... ``` rom.bin rom.ips rom.ips1 rom.ips2 ``` ...`rom.bin` will have `rom.ips`, `rom.ips1`, and `rom.ips2` applied to it in that order. ## **Cores Compatibility** ### Bandai - WonderSwan/Color | Core | Supported | |--------------------------------------------|:---------:| | [Beetle Cygne](../library/beetle_cygne.md) | ✔ | ### Coleco - ColecoVision | Core | Supported | |--------------------------------------------|:---------:| | [Gearcoleco](../library/gearcoleco.md) | ✔ | ### NEC PC Engine - TurboGrafx-16 / PC Engine CD - TurboGrafx-CD | Core | Supported | |--------------------------------------------|:---------:| | [Geargrafx](../library/geargrafx.md) | ✔ | ### Nintendo - DS | Core | Supported | |------------------------------------|:---------:| | [melonDS DS](../library/melonds_ds.md) | ✔ | ### Nintendo - Game Boy / Color | Core | Supported | |------------------------------------|:---------:| | [Gambatte](../library/gambatte.md) | ✔ | | [Gearboy](../library/gearboy.md) | ✔ | | [Mesen-S](../library/mesen-s.md) | ✔ | | [mGBA](../library/mgba.md) | ✔ | | [SameBoy](../library/sameboy.md) | ✕ | | [TGB Dual](../library/tgb_dual.md) | ✔ | | [VBA-M](../library/vba_m.md) | ✔ | ### Nintendo - Game Boy Advance | Core | Supported | |------------------------------------|:---------:| | [Meteor](../library/meteor.md) | ✔ | | [mGBA](../library/mgba.md) | ✔ | | [VBA-M](../library/vba_m.md) | ✔ | | [VBA Next](../library/vba_next.md) | ✔ | ### Nintendo - NES / Famicom | Core | Supported | |------------------------------------------|:---------:| | [bnes](../library/bnes.md) | ✔ | | [FCEUmm](../library/fceumm.md) | ✔ | | [Mesen](../library/mesen.md) | ✔ | | [Nestopia](../library/nestopia.md) | ✔ | | [QuickNES](../library/quicknes.md) | ✔ | ### Nintendo - SNES / Famicom | Core | Supported | |----------------------------------------------------------------------|:---------:| | [Beetle bsnes](../library/beetle_bsnes.md) | ✔ | | [bsnes-mercury Accuracy](../library/bsnes_mercury_accuracy.md) | ✔ | | [bsnes-mercury Balanced](../library/bsnes_mercury_balanced.md) | ✔ | | [bsnes-mercury Performance](../library/bsnes_mercury_performance.md) | ✔ | | [bsnes Accuracy](../library/bsnes_accuracy.md) | ✔ | | [bsnes Balanced](../library/bsnes_balanced.md) | ✔ | | [bsnes C++98 (v085)](../library/bsnes_cplusplus98.md) | ✔ | | [bsnes Performance](../library/bsnes_performance.md) | ✔ | | [higan Accuracy](../library/higan_accuracy.md) | ✔ | | [nSide Balanced](../library/nside_balanced.md) | ✔ | | [Mesen-S](../library/mesen-s.md) | ✔ | | [Snes9x](../library/snes9x.md) | ✔ | | [Snes9x 2002](../library/snes9x_2002.md) | ✔ | | [Snes9x 2005](../library/snes9x_2005.md) | ✔ | | [Snes9x 2005 Plus](../library/snes9x_2005_plus.md) | ✔ | | [Snes9x 2010](../library/snes9x_2010.md) | ✔ | ### Sega - Master System | Core | Supported | |--------------------------------------------------|:---------:| | [SMS Plus GX](../library/smsplus.md) | ✔ | | [Gearsystem](../library/gearsystem.md) | ✔ | | [Genesis Plus GX](../library/genesis_plus_gx.md) | ✕ | | [PicoDrive](../library/picodrive.md) | ✕ | ### Sega - MegaDrive / Genesis | Core | Supported | |--------------------------------------------------|:---------:| | [BlastEm](../library/blastem.md) | ✔ | | [ClownMDEmu](../library/clownmdemu.md) | ✔ | | [Genesis Plus GX](../library/genesis_plus_gx.md) | ✔ | | [PicoDrive](../library/picodrive.md) | ✕ | ### SNK - Neo Geo Pocket / Neo Geo Pocket Color | Core | Supported | |----------------------------------------------|:---------:| | [Beetle NeoPop](../library/beetle_neopop.md) | ✔ | | [RACE](../library/race.md) | ✕ | [^1]: When enabled at compile-time. ================================================ FILE: docs/guides/softwarelist-getting-started.md ================================================ # Getting started with Non-Acrcade/Software Emulation in Libretro MAME/MESS cores In this chapter, the terms 'software' and 'software lists' are used to define non-arcade machines that are emulated by MAME/MESS. This kind of emulation requires a different planning approach than arcade machine emulation - it is more complicated to set up. The basic principle is that software lists contained in the hash database are used to tell MAME/MESS how to start the game. This is an example entry from an Atari 7800 game also used further below (just for illustration purposes, no need to configure anything): Asteroids (NTSC) 1984 Atari ## Understand the core variants The libretro core ecosystem currently includes many multi software emulators that support software emulation. Three families exist: MAME, MESS and UME. These emulators are in turn available in multiple versions to allow users to best match a core to their preference. #### MAME current Arcade (MAME) is currently the only MAME core for most host systems that supports the emulation of both software & arcade systems. The Arcade (MAME) core is updated regularly and most of the time in line with the official MAME project release. For an overview of the vast number of system that are emulated, have a look into the github directory of the hash files: https://github.com/mamedev/mame/tree/master/hash - every xml contains the readable metadata of one system, i.e. the games it supports. Arcade (MAME 2016) is an archived snapshot of MAME from the 0.174 release. Currently it is no longer built for RetroArch. #### MESS (no longer provided) Currently there is no dedicated MESS core in Retroarch, except for Android ARM64. It is also still provided in RetroPie as MESS2016_libretro core. Multi (MESS 2016) is a snapshot of the MESS project from v0.160. The MESS project later merged with the MAME project in MAME v0.162, i.e. in May 2015. The documentation of MESS is here: http://mess.redump.net/start - however some of its pages no longer work. #### UME (no longer provided) UME cores are no longer in RetroArch. Multi (UME 2015) was a snapshot of the Universal Machine Emulator. This was a precursor to the MAME/MESS merger, released by David Haywood (haze). The MAME and MESS project codebases co-existed in the MESS SVN development tree before they officially merged. This allowed haze to build and release the emulator with unmodified code from both projects under the name UME. ## Use the correct version of romset for the desired emulator Arcade (MAME) will be the focus of this guide, but also the old Arcade (MAME 2016), the MULTI (MESS 2015) and MULTI (UME 2015) cores had this ability (so this information is also provided for documentation purposes). As in MAME arcade emulation, each core requires its own distinct version of software list "romsets", which the emulator supports. | Emulator | Required ROM Version | Notes | | :---: | :---: | :---: | | MAME (latest version) | MAME (latest version) | or same version if not in sync with MAME upstream | | MAME 2016 | MAME 0.174 | RetroArch core no longer provided | | MESS 2015 | MAME 0.160 | RetroArch core no longer provided | | UME 2015 | MAME 0.160 | RetroArch core no longer provided | !!! tip For best results, start with a full software list ROM collection with a version that matches the emulator you are using. Individual romset zip files may not include BIOS ROMs, "Parent" romsets, necessary audio sample files, etc. Matching emulator and game versions is advised for maximum compatibility, but you may find mis-matched combinations also work. --- ## Running software list machines There are two ways of configuring Retroarch to launch software list machines and games with MAME cores. 1. **Method 1 - MAME Frontend direct launch:** uses the inbuilt MAME logic and hash files to launch your games 2. **Method - RetroArch fontend friendly via Libretro CMD file launch:** uses an extra libretro feature to pass command line functions to the core ### Method 1: MAME Frontend direct launch For using the internal software list functions of MAME, you will need the right supporting files from the mainline MAME standalone emulator, i.e. the **hash files**. E.g. for the MAME (current) core, download the newest version of the Windows MAME emulator [here](https://www.mamedev.org/release.html). For earlier versions, make sure to get the correct version you require: The version of the hash files must match with the Libretro Core version. !!! tip In RetroArch, launch the desired core standalone, and on the bottom left, you find the correct MAME version that you want to download. Extract the contents and take the “hash” folder. Move this folder into the RetroArch folder structure. If your device has limited storage, just copy the hash files relating to the system you want to emulate. **RetroArch MAME system folder structure:** Folder structure/naming is very important here. The naming will depend on the machine you are trying to emulate but the folder structure will be the same. The example below is for the Atari 7800 system in MAME current. “YourPath” is the location of your Retroarch system folders. It varies depending on your operating system. !!! tip In RetroArch, head for Settings/Directory - the System/BIOS entry identifies the correct "system" folder. If not already existent, create the following folder in your RetroArch “system” folder: "YourPath"/Retroarch/System/mame Copy the hash folder acquired earlier into the RetroArch system folder: "YourPath"/Retroarch/system/mame/hash So for Atari 7800 you would have the following hash file: YourPath/Retroarch/system/mame/hash/a7800.xml (To do: check about .hsi file or use another example) **RetroArch MAME games folder structure:** Create the following folders in your games directory of your choice (these will be mame naming dependent) "YourPath"/Games/Atari 7800/a7800 (The last folder MUST be named as MAME requires, in this case “a7800”) Place any .zip games and .zip bios files required here: "YourPath"/Games/Atari 7800/a7800.zip "YourPath"/Games/Atari 7800/a7800/asteroid.zip !!! note To place the bios file above a7800 is the way that official MAME stores the data and thus also recommended here. You could also put the bios into the a7800 folder, but that's not how official MAME does it. You may also put or even extract the bios file to their own folder within the games directory "YourPath"/Games/Atari 7800/a7800/a7800/7800.rom Now launch the game: In RetroArch, choose "Load Content" and browse to asteroid.zip and launch with MAME current. (To Do: Add note about SoftList xml specifying the game names and crc and only supporting only those specific file names. Dummy files for CD-based games.) ### Method 2: RetroArch frontend friendly via Libretro CMD file launching This method follows the same folder structure as above, but you can use custom naming outside of the hash file included with MAME. It utilises some custom additions to the Libretro MAME Cores. Specifically the use of text files (.cmd) to replicate sending command line actions as you can with mainline MAME. **Creating a .cmd file** Let's follow the above example and create a dedicated asteroid.cmd file for the Atari 7800 game. It needs this line: a7800 -cart asteroid -rp "/"YourPath"/mame/roms/a7800" To do: Other path definitions, e.g. under Windows? Maybe explain the different sources, e.g. cart, flop etc? Now launch the game: In RetroArch, choose "Load Content" and browse to asteroid.cmd, and it should launch with MAME current. To do: Cmd file example ================================================ FILE: docs/guides/starting-a-game.md ================================================ # Starting a game ## Requirements * To load a game you need two things: A libretro core, and a ROM file. * Some systems/games may also require additional system files (such as a [BIOS](bios.md) to run correctly. ## via 'Load Content/Core' ### Load the core * Select `Load Core> Core` from the main menu, then choose a libretro core from the list. * Some releases of RetroArch come with a supply of cores built-in. If you don't have any cores installed, or want to add new ones, connect to the internet and select `Download a Core` from the bottom of the list. * Select your core in the list to load it. *See [Download Cores](download-cores.md).* When a libretro core is loaded, you will see the name and version of the core in the bottom left of the screen (Ozone/XMB/RGUI) or in the notification bar (GLUI). ### Load the content You can then browse for a ROM by selecting `Load Content`. Browse to your content's folder and select your ROM from the list. Then select `Current Core` or select another core from this list. The content will now launch. To set the folder for the `Start Directory` option (which will otherwise start in the user's root directory), set `File Browser` in `Settings> Directory`. *See [File Browser](file-browser.md)* ## via Playlists Alternatively, you can launch content from Playlists. * Scan for content to add to the playlist. *See [File Browser](file-browser.md) and [Import Content](import-content.md).* * Open your chosen Playlist. * Highlight your chosen row and select it. A new submenu will appear: Select `Run` to start the game. * If you have already `Set Core Association`, then the content will launch immediately. If you have not, one more list will ask you which Core you want to run the Content with. This option will automatically choose the "best" core to run the content. ## History / Favorites Content can be launched the 'History' and 'Favorites' playlists the same way as a regular Playlist. ### Exiting a game Press the key/button combination to open the [Quick Menu](quick-menu.md) and select `Close Content`. This will safely close both the Content and its Core, and return you to the Main Menu of RetroArch. ================================================ FILE: docs/guides/themes.md ================================================ # Making Custom Themes This page will guide you through the essential information needed to customize the core RetroArch theme. Credit for information goes to @baxysquare from this [forum post](https://forums.libretro.com/t/guide-to-making-themes/9554) !!! tip For examples of Menu Icon Themes and how to change them please read [this guide](https://github.com/libretro/docs/blob/master/docs/guides/theme-examples.md) ## Skills & Tools Needed to Make and Contribute a Theme * A GitHub account and a basic understanding on how to fork a project and contribute via Pull Requests. The GitHub project that hosts the theme is the [retroarch-assets](https://github.com/libretro/retroarch-assets) repository. * Computer application(s) to create source icons. You can use any photo editing application such as Photoshop or GIMP, but a Vector-based application such as Illustrator or Inkscape is preferred. The preferred source format is SVG. * Conversion applications can come in handy. You can use ImageMagick to batch convert your source files to PNG format. Running your PNG files through ImageOptim can help reduce the icon file size without reducing the quality. * Attention to detail, patience and time. Be prepared to create and revise as you learn and grow. Feel free to take an existing theme, make modifications and then test your new design. ## Required Theme Components * A truetype font renamed to "font.ttf." You need to choose a typeface that has an open license. There is a wide selection to choose from at [Google Fonts](https://fonts.google.com/). If you have the tools and skills to make your own font and wish to contribute it via open license, feel free to do so. * A text file in GitHub Markdown format titled README.md. This file provides basic info on the theme itself along with specifications and guidelines to help others contribute to the theme. Make sure to include an attribution and license info for the included truetype font. * A PNG folder that contains a complete set of icons and a default background image. ### Optional Theme Components * A SRC file containing SVG or other source files. If you choose not to include your source files, please host them elsewhere and indicate in the README. ## Icons The majority of time and effort involved in creating a theme is creating and revising the icons. The default Monochrome set includes just over 200 icons as listed below. That number will continue to grow as more cores and features are added. ## Tips & Tricks for Creating Icons * The icons should be set to a 256x256 pixel canvas and should be centered on a 64x64 grid. You need to snap your point and line elements to the grid wherever possible. Libretro icons are scaled down, so when design elements do not line up with the grid, they tend to render oddly. * Give your icons room to breathe. While you are capable of using the full canvas, a 248x248 or 240x240 maximum icon size is highly recommended. Alternatively, you can keep your icons inside a 256x256 circular "blueprint". This will keep the top and the bottom of your icons from touching when you're scrolling through a list of icons. * Create and stick to a color palette of 64 colors or less. While you can use an unlimited palette, your icons will look more uniform and consistent as a theme. * Keep the details of your icons in harmony with one another. If one icon has too many design details, try to simplify it to match with the other icons. If an icon is lacking in detail, do what you can to add balance in comparison to the other designs. Here's a complete list of icons (and wallpaper) in the default set. Category, Type, Menu Level and Size info has been included to help you understand an icon's purpose and use in the user interface. | Name | Category | Type | Level | Size | |------------------------------------------------------------|----------|-------------|-------|-------| | FB Alpha - Arcade Games-content.png | Arcade | Content | 1 | 256 | | MAME-content.png | Arcade | Content | 1 | 256 | | MAME2003-content.png | Arcade | Content | 1 | 256 | | MAME2010-content.png | Arcade | Content | 1 | 256 | | Neo Geo-content.png | Arcade | Content | 1 | 256 | | FB Alpha - Arcade Games.png | Arcade | System | 0 | 256 | | MAME.png | Arcade | System | 0 | 256 | | MAME2003.png | Arcade | System | 0 | 256 | | MAME2010.png | Arcade | System | 0 | 256 | | Neo Geo.png | Arcade | System | 0 | 256 | | Lutro.png | Computer | Application | 0 | 256 | | DOS.png | Computer | Application | 0 | 256 | | Atari - ST-content.png | Computer | Content | 1 | 256 | | Commodore Amiga-content.png | Computer | Content | 1 | 256 | | DOS-content.png | Computer | Content | 1 | 256 | | Microsoft - MSX-content.png | Computer | Content | 1 | 256 | | Microsoft - MSX2-content.png | Computer | Content | 1 | 256 | | ScummVM-content.png | Computer | Content | 1 | 256 | | Sinclair - ZX 81-content.png | Computer | Content | 1 | 256 | | Sinclair - ZX Spectrum +3-content.png | Computer | Content | 1 | 256 | | Sinclair - ZX Spectrum-content.png | Computer | Content | 1 | 256 | | Lutro-content.png | Computer | Content | 1 | 256 | | Atari - ST.png | Computer | System | 0 | 256 | | Commodore Amiga.png | Computer | System | 0 | 256 | | Microsoft - MSX.png | Computer | System | 0 | 256 | | Microsoft - MSX2.png | Computer | System | 0 | 256 | | ScummVM.png | Computer | System | 0 | 256 | | Sinclair - ZX 81.png | Computer | System | 0 | 256 | | Sinclair - ZX Spectrum +3.png | Computer | System | 0 | 256 | | Sinclair - ZX Spectrum.png | Computer | System | 0 | 256 | | Atari - 2600-content.png | Console | Content | 1 | 256 | | Atari - 5200-content.png | Console | Content | 1 | 256 | | Atari - 7800-content.png | Console | Content | 1 | 256 | | Atari - Jaguar-content.png | Console | Content | 1 | 256 | | Bandai - WonderSwan Color-content.png | Console | Content | 1 | 256 | | Bandai - WonderSwan-content.png | Console | Content | 1 | 256 | | Coleco - ColecoVision-content.png | Console | Content | 1 | 256 | | GCE - Vectrex-content.png | Console | Content | 1 | 256 | | Magnavox - Odyssey2-content.png | Console | Content | 1 | 256 | | NEC - PC Engine - TurboGrafx 16-content.png | Console | Content | 1 | 256 | | NEC - PC Engine CD - TurboGrafx-CD-content.png | Console | Content | 1 | 256 | | NEC - PC Engine SuperGrafx-content.png | Console | Content | 1 | 256 | | NEC - PC-FX-content.png | Console | Content | 1 | 256 | | Nintendo - Family Computer Disk System-content.png | Console | Content | 1 | 256 | | Nintendo - GameCube-content.png | Console | Content | 1 | 256 | | Nintendo - Nintendo 64-content.png | Console | Content | 1 | 256 | | Nintendo - Nintendo 64DD-content.png | Console | Content | 1 | 256 | | Nintendo - Nintendo Entertainment System-content.png | Console | Content | 1 | 256 | | Nintendo - Satellaview-content.png | Console | Content | 1 | 256 | | Nintendo - Sufami Turbo-content.png | Console | Content | 1 | 256 | | Nintendo - Super Nintendo Entertainment System-content.png | Console | Content | 1 | 256 | | Nintendo - Wii-content.png | Console | Content | 1 | 256 | | Sega - 32X-content.png | Console | Content | 1 | 256 | | Sega - Dreamcast-content.png | Console | Content | 1 | 256 | | Sega - Master System - Mark III-content.png | Console | Content | 1 | 256 | | Sega - Mega Drive - Genesis-content.png | Console | Content | 1 | 256 | | Sega - Mega-CD - Sega CD-content.png | Console | Content | 1 | 256 | | Sega - PICO-content.png | Console | Content | 1 | 256 | | Sega - Saturn-content.png | Console | Content | 1 | 256 | | Sega - SG-1000-content.png | Console | Content | 1 | 256 | | SNK - Neo Geo CD-content.png | Console | Content | 1 | 256 | | SNK - Neo Geo-content.png | Console | Content | 1 | 256 | | Sony - PlayStation-content.png | Console | Content | 1 | 256 | | The 3DO Company - 3DO-content.png | Console | Content | 1 | 256 | | Uzebox-content.png | Console | Content | 1 | 256 | | Atari - 2600.png | Console | System | 0 | 256 | | Atari - 5200.png | Console | System | 0 | 256 | | Atari - 7800.png | Console | System | 0 | 256 | | Atari - Jaguar.png | Console | System | 0 | 256 | | Bandai - WonderSwan Color.png | Console | System | 0 | 256 | | Bandai - WonderSwan.png | Console | System | 0 | 256 | | Coleco - ColecoVision.png | Console | System | 0 | 256 | | GCE - Vectrex.png | Console | System | 0 | 256 | | Magnavox - Odyssey2.png | Console | System | 0 | 256 | | NEC - PC Engine - TurboGrafx 16.png | Console | System | 0 | 256 | | NEC - PC Engine CD - TurboGrafx-CD.png | Console | System | 0 | 256 | | NEC - PC Engine SuperGrafx.png | Console | System | 0 | 256 | | NEC - PC-FX.png | Console | System | 0 | 256 | | Nintendo - Family Computer Disk System.png | Console | System | 0 | 256 | | Nintendo - GameCube.png | Console | System | 0 | 256 | | Nintendo - Nintendo 64.png | Console | System | 0 | 256 | | Nintendo - Nintendo 64DD.png | Console | System | 0 | 256 | | Nintendo - Nintendo Entertainment System.png | Console | System | 0 | 256 | | Nintendo - Satellaview.png | Console | System | 0 | 256 | | Nintendo - Sufami Turbo.png | Console | System | 0 | 256 | | Nintendo - Super Nintendo Entertainment System.png | Console | System | 0 | 256 | | Nintendo - Wii.png | Console | System | 0 | 256 | | Sega - 32X.png | Console | System | 0 | 256 | | Sega - Dreamcast.png | Console | System | 0 | 256 | | Sega - Master System - Mark III.png | Console | System | 0 | 256 | | Sega - Mega Drive - Genesis.png | Console | System | 0 | 256 | | Sega - Mega-CD - Sega CD.png | Console | System | 0 | 256 | | Sega - PICO.png | Console | System | 0 | 256 | | Sega - Saturn.png | Console | System | 0 | 256 | | Sega - SG-1000.png | Console | System | 0 | 256 | | SNK - Neo Geo CD.png | Console | System | 0 | 256 | | SNK - Neo Geo.png | Console | System | 0 | 256 | | Sony - PlayStation.png | Console | System | 0 | 256 | | The 3DO Company - 3DO.png | Console | System | 0 | 256 | | Uzebox.png | Console | System | 0 | 256 | | Atari - Lynx-content.png | Handheld | Content | 1 | 256 | | Game Park - GP32-content.png | Handheld | Content | 1 | 256 | | Handheld Electronic Game-content.png | Handheld | Content | 1 | 256 | | Nintendo - Game Boy Advance-content.png | Handheld | Content | 1 | 256 | | Nintendo - Game Boy Color-content.png | Handheld | Content | 1 | 256 | | Nintendo - Game Boy-content.png | Handheld | Content | 1 | 256 | | Nintendo - Nintendo DS Decrypted-content.png | Handheld | Content | 1 | 256 | | Nintendo - Nintendo DS-content.png | Handheld | Content | 1 | 256 | | Nintendo - Pokemon Mini-content.png | Handheld | Content | 1 | 256 | | Nintendo - Virtual Boy-content.png | Handheld | Content | 1 | 256 | | Sega - Game Gear-content.png | Handheld | Content | 1 | 256 | | SNK - Neo Geo Pocket Color-content.png | Handheld | Content | 1 | 256 | | SNK - Neo Geo Pocket-content.png | Handheld | Content | 1 | 256 | | Sony - PlayStation Portable-content.png | Handheld | Content | 1 | 256 | | Tiger - Game.com-content.png | Handheld | Content | 1 | 256 | | Atari - Lynx.png | Handheld | System | 0 | 256 | | Game Park - GP32.png | Handheld | System | 0 | 256 | | Handheld Electronic Game.png | Handheld | System | 0 | 256 | | Nintendo - Game Boy Advance.png | Handheld | System | 0 | 256 | | Nintendo - Game Boy Color.png | Handheld | System | 0 | 256 | | Nintendo - Game Boy.png | Handheld | System | 0 | 256 | | Nintendo - Nintendo DS Decrypted.png | Handheld | System | 0 | 256 | | Nintendo - Nintendo DS.png | Handheld | System | 0 | 256 | | Nintendo - Pokemon Mini.png | Handheld | System | 0 | 256 | | Nintendo - Virtual Boy.png | Handheld | System | 0 | 256 | | Sega - Game Gear.png | Handheld | System | 0 | 256 | | SNK - Neo Geo Pocket Color.png | Handheld | System | 0 | 256 | | SNK - Neo Geo Pocket.png | Handheld | System | 0 | 256 | | Sony - PlayStation Portable.png | Handheld | System | 0 | 256 | | Tiger - Game.com.png | Handheld | System | 0 | 256 | | 2048.png | Port | Application | 0 | 256 | | Cave Story.png | Port | Application | 0 | 256 | | Dinothawr.png | Port | Application | 0 | 256 | | DOOM.png | Port | Application | 0 | 256 | | Dungeon Crawl Stone Soup.png | Port | Application | 0 | 256 | | Quake1.png | Port | Application | 0 | 256 | | 2048-content.png | Port | Content | 1 | 256 | | Cave Story-content.png | Port | Content | 1 | 256 | | Dinothawr-content.png | Port | Content | 1 | 256 | | DOOM-content.png | Port | Content | 1 | 256 | | Dungeon Crawl Stone Soup-content.png | Port | Content | 1 | 256 | | Quake1-content.png | Port | Content | 1 | 256 | | FFmpeg.png | XMB | Application | 0 | 256 | | default.png | XMB | Application | 0 | 256 | | Game.png | XMB | Application | 0 | 256 | | history.png | XMB | Application | 0 | 256 | | images.png | XMB | Application | 0 | 256 | | lakka.png | XMB | Application | 0 | 256 | | movies.png | XMB | Application | 0 | 256 | | netplay.png | XMB | Application | 0 | 256 | | retroarch.png | XMB | Application | 0 | 256 | | settings.png | XMB | Application | 0 | 256 | | musics.png | XMB | Application | 0 | 256 | | add.png | XMB | Application | 0 | 256 | | FFmpeg-content.png | XMB | Content | 1 | 256 | | music.png | XMB | Content | 1 | 256 | | image.png | XMB | Content | 1 | 256 | | movie.png | XMB | Content | 1 | 256 | | achievement-list.png | XMB | Content | 1 | 256 | | default-content.png | XMB | Content | 1 | 256 | | Game-content.png | XMB | Content | 1 | 256 | | netplay - iRoom-locked.png | XMB | Content | 1 | 256 | | netplay - iRoom.png | XMB | Content | 1 | 256 | | netplay - LAN Room-locked.png | XMB | Content | 1 | 256 | | netplay - LAN Room.png | XMB | Content | 1 | 256 | | netplay - rooms-locked.png | XMB | Content | 1 | 256 | | netplay - rooms.png | XMB | Content | 1 | 256 | | room.png | XMB | Content | 1 | 256 | | setting.png | XMB | Content | 1 | 256 | | zip.png | XMB | Content | 2 | 256 | | file.png | XMB | Content | 2 | Small | | folder.png | XMB | Content | 2 | Small | | dialog-slice.png | XMB | Dialog | 2 | 256 | | Libretro - Pad.png | XMB | Help | - | 256 | | battery-charging.png | XMB | Info Bar | - | Small | | battery-full.png | XMB | Info Bar | - | Small | | clock.png | XMB | Info Bar | - | Small | | undo.png | XMB | Info Bar | - | Small | | wifi.png | XMB | Info Bar | - | Small | | key-hover.png | XMB | Key | 2 | 256 | | key.png | XMB | Key | 2 | 256 | | arrow.png | XMB | Nav | 2 | Small | | close.png | XMB | Nav | 2 | Small | | core-cheat-options.png | XMB | Nav | 2 | Small | | core-disk-options.png | XMB | Nav | 2 | Small | | core-infos.png | XMB | Nav | 2 | Small | | core-input-remapping-options.png | XMB | Nav | 2 | Small | | core-options.png | XMB | Nav | 2 | Small | | core-shader-options.png | XMB | Nav | 2 | Small | | core.png | XMB | Nav | 2 | Small | | cursor.png | XMB | Nav | 2 | Small | | database.png | XMB | Nav | 2 | Small | | loadstate.png | XMB | Nav | 2 | Small | | pointer.png | XMB | Nav | 2 | Small | | reload.png | XMB | Nav | 2 | Small | | resume.png | XMB | Nav | 2 | Small | | run.png | XMB | Nav | 2 | Small | | savestate.png | XMB | Nav | 2 | Small | | screenshot.png | XMB | Nav | 2 | Small | | subsetting.png | XMB | Nav | 2 | Small | | off.png | XMB | Selection | 2 | Small | | on.png | XMB | Selection | 2 | Small | | bg.png | XMB | Wallpaper | - | 1080p | ================================================ FILE: docs/guides/troubleshooting-retroarch.md ================================================ # Troubleshooting RetroArch ## Common video issues ### Optimal vsync performance with dynamic rate control RetroArch uses Dynamic Rate Control to synchronize both video and audio at the same time. Synchronizing like this is a very demanding task timing-wise and dynamic rate control helps smooth out imperfections in timing which are guaranteed to arise. It can be disabled, but be aware that proper video/audio sync is nearly impossible to obtain. While using RetroArch, the default settings might not be adequate, and you might experience video stuttering and/or audio crackling. For correct synchronization, video_refresh_rate must be configured for your monitor. It cannot be detected accurately enough by OS-provided APIs (i.e. they tend to blatantly lie). For proper behavior, an accuracy of roughly ~0.1% is needed for dynamic rate control to smooth out the drifting. This is trivial to obtain by measuring manually under normal conditions. Without dynamic rate control one would need a "perfect" measurement which obviously isn't possible without special hardware. RetroArch can give you an estimate of your monitors refresh rate under video settings, which is updated in real-time using a running average over frame times. Make sure vysnc is enabled and working. Also make sure you're running in full-screen for more accurate results (compositors can easily interfere with timing). Press accept button on the estimated refresh rate to configure RetroArch with the estimated rate. If the running average isn't drifting much anymore, it's probably a good result. You can also have RetroArch log the output at the end and configure things more manually. Start RetroArch directly in RGUI with retroarch --verbose --menu. Let it run uninterrupted for at least 4096 frames (displayed in title bar), and exit. In the log, you should see something like: RetroArch: Average monitor Hz: 59.869485 Hz. (1.347 % frame time deviation, based on 2048 last samples). If you're unsure about the result, run this test several times and see if the results are consistent. Some systems tend to have very unreliable vsync behavior and this result will wildly fluctuate. You can use this value in `video_refresh_rate` and the video and audio should ideally be butter smooth if the game's FPS and monitor FPS are relatively close to each other. Playing a PAL game on 60 Hz monitor won't be perfect no matter what you do, however. ### Threaded video If your video driver has very bad performance, it is possible to run it on a thread to avoid almost all video driver overhead. Set video_threaded = true in config. Butter smooth VSync behavior in this case is impossible however, and latency might increase slighly. Use only if you cannot obtain full speed otherwise. ### Low frame rate - Make sure your system meets the requirement of the core you picked - See if your core options aren't set too high for your system - Disable shaders - Lower the video scale setting - Try another video driver - Try enabling threaded video in the video options - Try disabling VSYNC - Disable Run-Ahead in the Latency options ### Windows Vista and up video problems Windows Vista and up suffer problems with OpenGL in windowed mode where it appears to be impossible to obtain proper, smooth VSync behavior no matter what you do. If you are annoyed by this problem, and still want to play in windowed mode, you should use the D3D driver which doesn't have this problem. Disabling Aero sometimes helps OpenGL VSync behavior. ## Input latency There have been cases reported on excessive input lag in Windows for some users. It's not really input latency, but video driver latency. Some video drivers tend to buffer way too much in the name of increased performance. This problem is explained by Carmack here. RetroArch recently got an option to use a swap/fence sync method in OpenGL driver, which is reported to greatly lower input latency (thread). To enable it, set video_hard_sync = true in config or enable it from RGUI. To ensure that this sync method is actually used, make sure that you see this in the log: RetroArch: Querying GL extension: ARB_sync => exists RetroArch: [GL]: Using ARB_sync to reduce latency. Do note that this sync method can greatly reduce performance, and can turn smooth 60 fps into crawling 30 fps if there was not enough headroom in the performance. If you use KMS mode, using `video_hard_sync` won't help as it already does something like this. ## Why isn’t my BIOS working? 1. Make sure the BIOS files are placed into the correct directory 2. Make sure they are named correctly so the core can identify them. 3. Make sure it’s the correct version/region of a BIOS. 4. Make sure your files are not corrupted (bad source, broken download, etc.). 5. Make sure to check the log for any errors. # Getting ready to ask for help When problems arise with RetroArch, it is helpful for the developers and other volunteers to have certain standard information in order to find a solution. When requesting help with a RetroArch issue, please try to include: 1. A description of the problem: What did you expect to happen, and what happened instead? 2. The version of RetroArch you are using 3. The hardware and operating system that you are using 4. If the problem occurs while using a core: What is the the core name, its version, and the name of the game or media you were playing? 5. RetroArch log files recorded when the problem occurs See: Generating RetroArch Logs ## "OK, I've done these things. Where can I get help?" If you have questions or issues which cannot be resolved on your own, visit [the RetroArch forum](http://forums.libretro.com/) ## "I know my problem is a bug. Where can I report it?" You can report issues in the [RetroArch issues tracker](https://github.com/libretro/RetroArch/issues). ================================================ FILE: docs/guides/tv.md ================================================ # TV ## The default picture mode may cause controller-to-screen latency Most TVs—both smart and non‑smart—ship with preconfigured picture modes that are not intended for gaming (for example, “Standard“/“Default“, or “Eco”). These modes introduce screen latency during gameplay. The delay between pressing a controller button and seeing the corresponding action on-screen can disrupt gameplay rhythm and offset any system or emulator optimizations for low latency. Budget LED models typically have the highest latency (around 40–70 ms), whereas OLED panels perform better. Note that this latency issue is TV related; Computer monitors (LCD/LED, CRT, etc.) avoid this issue entirely, as they are designed for interactive use with inherently minimal input lag across all modes. ### Picture mode fix #### Modern TVs: Switch to "Game" picture mode On the TV, navigate to **Settings → Picture Mode/Style**, and select “Game”. This addresses the root cause of input lag. Even if you don't notice any latency on the TV model, it's still good practice to enable this mode to ensure minimal input lag. Auto Low Latency Mode (ALLM) is not helpful for RetroArch. While ALLM—often found in gaming TVs—automatically detects gaming signals (such as from a console or streaming device) and switches to a low-latency preset, allowing you to keep picture modes like Cinema or Sports active during gameplay before reverting when the signal changes (e.g., to a movie), RetroArch typically does not send the required HDMI ALLM gaming flag. Manual activation of Game Mode remains essential for emulation setups. Thus, understanding that the manufacturer ALLM features with various names listed below are useless for RetroArch saves you from wasting time evaluating them: | Manufacturer | Common Name(s) for ALLM | |--------------|--------------------------------------| | Hisense | Game Mode Pro | | LG | Instant Game Response, Game Optimizer | | Panasonic | Auto Low Latency Mode | | Philips | Auto Low Latency Mode | | Samsung | Auto Game Mode | | Sony | Auto Genre Picture Mode | | TCL | Auto Game Mode, Game Master | | Vizio | Auto Game Mode, ProGaming Engine | #### Older TVs: Enable RetroArch `Run-Ahead` For older TVs without a "Game" picture mode, use RetroArch's `Settings` → `Latency` → `Run-Ahead` feature to reduce latency effectively. ### Optionally: Use RetroArch's Shaders and Overlays Shaders and overlays in RetroArch may be used instead of TV picture modes to apply authentic retro display effects and decorative elements directly to the emulated image, bypassing the hardware-dependent post-processing in non-Game picture modes that introduces input lag. ## Frame rate fluctuations ### Frame rate fluctuations fix: Use RetroArch Synchronization features The Settings → Video → Synchronization menu in RetroArch provides several options to reduce screen tearing and stuttering by aligning frame output with the display’s refresh rate. These options—Vertical Sync (VSync) (default: On), Hard GPU Sync (default: Off), and Adaptive VSync (default: Off)—offer software-level synchronization that approximates some of the benefits of Variable Refresh Rate (VRR) found in many gaming TVs. This is necessary because RetroArch does not support native HDMI signaling to automatically enable VRR on compatible displays. ================================================ FILE: docs/guides/web-player.md ================================================ # What is it? It is a version that works on modern internet browsers with the basic features of RetroArch. You don't need to install this version. You can add your content after selecting the desired Core. ## How to use it You can access it from this [link](https://web.libretro.com/) using a modern internet browser (For example: Google Chrome, Microsoft Edge etc.). !!! Warning Using an old internet browser may ruin the whole experience. ![Loading core](../image/guides/web-player-1.jpg) 1. Select the **Core** to run from the **first tab**(Clicking on the Core name will start running). *Core loading time may vary depending on the selected Core. During this time, your system's performance and actively used processes can cause your browser to crash. In this case, the option Wait or End will be displayed on your screen. In this case, click Wait, it may come out several times.* ![Main Screen](../image/guides/web-player-2.jpg) 1. Choose your content to load by clicking **Add Content** from the **second tab**. *This will add your content to your browser's cache. We will be able to delete it later.* 1. To access the file you uploaded `Load Content> Start Directory >` *You will also see it in the Downloads folder, where you can access open source content, which you can download from RetroArch's Content Downloader.* ![Added content](../image/guides/web-player-3.jpg) ## Details We can use the basic features of RetroArch. - How can I toggle Quick Menu? - You can either press F1 or click the Menu Toggle button which is ![Menu Toggle](../image/guides/web-player-quick-menu.jpg) - How can I go full screen? - You do not want to press F11 when the screen is selected, this key usually takes you to full screen, but in our scenario you need to use the Full Screen key which is ![Fullscreen button](../image/guides/web-player-fullscreen-btn.jpg). - How can I delete the cache? - There are many methods for this, you can do CTRL + F5, right click the cursor and go to the inspect and right click on the refresh button on the top left and clear the cache, press the clear cache key ![Cleanup](../image/guides/web-player-cleanup.jpg). You can also click the `Help` button and read this information there. ### Cores Supported Cores for now are as follows, may vary in this list. ``` 2048 Beetle Lynx Beetle NeoPop Beetle PCE FAST Beetle PC-FX Beetle VB Beetle WonderSwan ChaiLove Craft FB Alpha 2012 FB Alpha 2012 CPS1 FB Alpha 2012 CPS2 FB Alpha 2012 NeoGeo FCEUmm FFmpeg Gambatte Game Music Emu Genesi Plus GX gPSP Handy MAME 2000 Mu Nestopia NX Engine 02em Opera PicoDrive PrBoom QuickNES Flycast Snes9x 2002 Snes9x 2005 Snes9x 2010 Snes9x SquirrelJME TGB Dual Theodore (Thompson T08/T09) TryQuake VBA Next Vecx Yabause ``` ================================================ FILE: docs/guides/xmb-menu-map.md ================================================ # XMB Menu Map ## Tabs ### Main Menu - Load Core ... / **Quick Menu** (Changes when a core is loaded) - **Load Content** - Start Directory ... - Downloads ... - Playlists - (Varies by platform/device) - **File Browser** (Duplicate/Shortcut to Settings > File Browser) - Show Desktop Menu - **Online Updater** - **Core Downloader** - (Availability of cores varies by platform/device) - Update Installed Cores - Playlist Thumbnails Updater - **Content Downloader** - Update Core Infor Files - Update Assets - Update Controller Profiles - Update Cheats - Update Databases - Update Overlays - Update (Slang/GLSL/Cg; varies by active video driver) Shaders - On-Demand Thumbnail Downloads - **Information** - **Network Information** - (Varies by device) - **System Information** - (Varies by device) - **Database Manager** - (Varies by available databases) - **Cursor Manager** - (Varies by available cursors) - **Configuration File** - Load Configuration ... - Reset to Defaults - Save Current Configuration - Save New Configuration - **Help** - Basic Menu Controls - Restart RetroArch - Quit RetroArch ### Settings - **Drivers** - Input - Controller - Video - Audio - Audio Resampler - Camera - Location - Menu - Record - MIDI - **Video** - **CRT SwitchRes** - CRT SwitchRes - CRT Super Resolution - X-Axis Centering - Porch Adjust - Use Custom Refresh Rate - **Output** - Video (Duplicate/Shortcut to Settings > Driver > video) - Monitor Index - Video Rotation - GPU Index - Vertical Refresh Rate - Estimated Screen Refresh Rate - Set Display-Reported Refresh Rate - **Fullscreen Mode** - Start in Fullscreen Mode - Windowed Fullscreen Mode - Fullscreen Width - Fullscreen Height - **Windowed Mode** - Windowed Scale - Window Opacity - Show Window Decorations - Remember Window Position and Size - Window Width - Window Height - **Scaling** - Integer Scale - Aspect Ratio - Custom Aspect Ratio - Crop Overscan - **Synchronization** - Vertical Sync (VSync) - Vsync Swap Interval - Frame Delay - Max swapchain images - Sync to Exact Content Framerate - Suspend Screensaver - Threaded Video - Black Frame Insertion - GPU Screenshot - Bilinear Filtering - Auto-Shader Delay - Video Filter ... - **Audio** - **Output** - Audio - Audio (Duplicate/Shortcut to Settings > Driver > Audio) - Device - Audio Latency (ms) - **Resampler** - Audio Resampler - Resampler Quality - Output Rate (Hz) - **Synchronization** - Synchronization - Maximum Timing Skew - Dynamic Audio Rate Control - **MIDI** - Input - Output - Volume - **Mixer** - Mixer Stream #1 - Mixer Stream #2 - Mixer Stream #3 - Mixer Stream #4 - Mixer Stream #5 - Mixer Stream #6 - Mixer Stream #7 - Mixer Stream #8 - Mixer Stream #9 - Mixer Stream #10 - Mixer Stream #11 - Mixer Stream #12 - Mixer Stream #13 - Mixer Stream #14 - Mixer Stream #15 - Mixer Stream #16 - **Menu Sounds** - Mixer - Enable 'OK' Sound - Enable 'Cancel' Sound - Enable 'Notice' Sound - Enable 'BGM' Sound - Mute - Mixer Mute - Mute When Fast-Forwarding - Volume Gain (dB) - Mixer Volume Gain (dB) - DSP Plugin ... - **Input** - Maximum Users - Polling Behavior - Remap Controls for This Core - Autoconfig - Input Button Axis Threshold - Touch Scale - Analog Deadzone - Analog Sensitivity - Bind Timeout - Bind Hold - Disable Windows Hotkeys (Restart) - Auxiliary Sensor Input - Auto Enable 'Game Focus' Mode - **Menu Controls** - Unified Menu Controls - Menu Swap OK and Cancel Buttons - Menu Scroll Acceleration - Menu Scroll Delay - **Hotkeys** - Confirm Quit - Menu Toggle Controller Combo - Hotkey Enable - Hotkey Enable Delay (Frames) - Fast-Forward (Toggle) - Fast-Forward (Hold) - Slow-Motion (Toggle) - Slow-Motion (Hold) - Load State - Save State - Fullscreen (Toggle) - Close Content - Quit RetroArch - Save State Slot + - Save State Slot - - Rewind - Record Input Replay (Toggle) - Pause (Toggle) - Frameadvance - Reset Game - Next Shader - Previous Shader - Next Cheat Index - Previous Cheat Index - Cheats (Toggle) - Take Screenshot - Audio Mute (Toggle) - On-Screen Keyboard (Toggle) - Show FPS (Toggle) - Send Debug Info - Netplay Hosting (Toggle) - Netplay Play/Spectate Mode (Toggle) - Volume Up - Volume Down - Next overlay - Disc Eject Toggle - Next Disc - Previous Disc - Grab Mouse (Toggle) - Game Focus (Toggle) - Desktop Menu (Toggle) - Menu (Toggle) - Recording (Toggle) - Streaming (Toggle) - Run-Ahead (Toggle) - AI Service - **Turbo Fire** - Turbo Period - Turbo Duty Cycle - Turbo Mode - Turbo Default Button - **Port 1 Controls** - Device Type - Analog to Digital Type - Device Index - Mouse Index - Set All Controls - Reset to Default Controls - Save Controller Profile - (RetroPad Mapping) - (Gun Mapping) - Turbo - **Port 2 Controls** - (Same as Port 1) - **Port 3 Controls** - (Same as Port 1) - **Port 4 Controls** - (Same as Port 1) - **Port 5 Controls** - (Same as Port 1) - (possibly more/less based on 'Maximum Users' setting) - **Latency** - Max swapchain images (Duplicate/Shortcut to Settings > Video > Synchronization > Max swapchain images) - Frame Delay - Audio Latency (ms) - Polling Behavior - **Run-Ahead to Reduce Latency** - Number of Frames to Run-Ahead - Use Second Instance for Run-Ahead - Hide Run-Ahead Warnings - **Core** - Hardware Shared Context - Allow Cores to Switch the Video Driver - Load Dummy on Core Shutdown - Check for Missing Firmware before Loading - Allow Rotation - Manage Cores - **Configuration** - Save Configuration on Quit - Load Content-Specific Core Option - Load Override Files Automatically - Load Remap Files Automatically - Use Global Core Options File - **Saving** - Sort Saves into Folders by Core Name - Sort Save States into Folders by Core Name - Sort Saves into Folders by Content Directory - Sort Save states into Folders by Content Directory - Don't Overwrite SaveRAM on Loading Save State - SaveRAM Autosave Interval - Increment Save State Index Automatically - Auto Save State - Load State Automatically - Save State Thumbnails - SaveRAM Compression - Save State Compression - Sort Screenshots into Folders by Content Directory - Write Saves to Content Directory - Write Save States to Content Directory - System Files are in Content Directory - Write Screenshots to Content Directory - Save Runtime Log (Per Core) - Save Runtime Log (Aggregate) - **Logging** - Logging Verbosity - Frontend Logging Level - Core Logging Level - Log to File - Performance Counters - **File Browser** - Show Hidden Files and Directories - Filter Unknown Extensions - Use Built-In Media Player - Use Built-In Image Viewer - Filter by Current Core - Remember Last Used Start Directory - **Frame Throttle** - **Rewind** - Rewind Support - Rewind Frames - Rewind Buffer Size (MB) - Rewind Buffer Size Step (MB) - **Frame Time Counter** - Estimated Screen Refresh Rate - Reset after Fast-Forward - Reset after Load State - Reset after Save State - Fast-Forward Rate - Slow-Motion Rate - Sync to Exact Content Framerate (Duplicate/Shortcut to Settings > Video > Synchronization > Sync to Exact Content Framerate) - Throttle Menu Framerate - **Recording** - Recording Quality - Custom recording Configuration ... - Recording Threads - Use Post Filter Recording - Use GPU Recording - Streaming Mode - Streaming Quality - Custom Streaming Configuration - Stream Title - Stream URL - UDP Stream Port - **On-Screen Display** - **On-Screen Overlay** - Display Overlay - Hide Overlay in Menu - Hide Overlay When Controller is Connected - Show Inputs on Overlay - Show Mouse Cursor With Overlay - Auto-Rotate Overlay - Auto-Scale Overlay - Overlay Preset ... - Overlay Opacity - (Landscape) Overlay Scale - (Landscape) Overlay Aspect Adjustment - (Landscape) Overlay Horizontal Separation - (Landscape) Overlay Vertical Separation - (Landscape) Overlay X Offset - (Landscape) Overlay Y Offset - (Portrait) Overlay Scale - (Portrait) Overlay Aspect Adjustment - (Portrait) Overlay Horizontal Separation - (Portrait) Overlay Vertical Separation - (Portrait) Overlay X Offset - (Portrait) Overlay Y Offset - **Video Layout** - Enable Video Layout - Video Layout Path ... - Selected View - **On-Screen Notification** - **Notification Visibility** - Display Framerate - Display Frame Count - Display Statistics - Display Memory Usage - "Load Content" Startup Notification - Input (Autoconfig) Connection Notification - Cheat Code Notifications - Input Remap Loaded Notifications - Config Override Loaded Notifications - Initial Disc Restored Notifications - Fast-Forward Notifications - Screenshot Notifications - Screenshot Notification Persistence - Screenshot Flash Effect - Refresh Rate Notifications - On-Screen Notifications - Graphics Widgets - Scale Graphics Widgets Automatically - Notification Font ... - Notification Size - **User Interface** - **Menu Item Visibility** - **Quick Menu** - Show 'Resume' - Show 'Restart' - Show 'Close Content' - Show 'Take Screenshot' - Show 'Save/Load State' - Show 'Undo Save/Load State' - Show 'Add to Favorites' - Show 'Start Recording' - Show 'Start Streaming' - Show 'Set Core Association' - Show 'Reset Core Association' - Show 'Options' - Show 'Controls' - Show 'Cheats' - Show 'Shaders' - Show 'Rewind' - Show 'Latency' - Show 'On-Screen Overlay - Show 'Video Layout - Show 'Save Core Overrides' - Show 'Save Game Overrides' - Show 'Information' - Show 'Download Thumbnails' - **Settings** - Show 'Drivers' - Show 'Video' - Show 'Audio' - Show 'Input' - Show 'Latency' - Show 'Core' - Show 'Configuration' - Show 'Saving' - Show 'Logging' - Show 'File Browser' - Show 'Recording' - Show 'On-Screen Display' - Show 'User Interface' - Show 'AI Service' - Show 'Accessibility' - Show 'Power Management' - Show 'Achievements' - Show 'Network' - Show 'Playlists' - Show 'User' - Show 'Directory' - Show 'Load Core' - Show 'Load Content' - Show 'Load Disc' - Show 'Dump Disc' - Show 'Online Updater' - Show 'Core Downloader' - Show Legacy 'Thumbnails Updater' - Show 'Information' - Show 'Configuration File' - Show 'Help' - Show 'Quit RetroArch' - Show 'Restart RetroArch' - Show 'Settings' - Set Password for Enabling 'Settings' - Show 'Explore' - Show 'Favorites' - Show 'Images' - Show 'Music' - Show 'Videos' - Show 'Netplay' - Show 'History' - Show 'Import Content' - Show 'Playlists' - Show Date and Time - Style of Date and Time - Date Separator - Show Battery Level - Show Core Name - Show Menu Sub-Labels - Display Start Screens - **Appearance** - Menu Scale Factor - Background Image ... - Dynamic Background - Background Opacity - Framebuffer Opacity - Horizontal Animation - Animation Horizontal Icon Highlight - Animation Move Up/Down - Animation Main Menu Opens/Closes - Menu Alpha Factor - Menu Font ... - Menu Font Color (Red) - Menu Font Color (Green) - Menu Font Color (Blue) - Menu Layout - Menu Icon Theme - Icon Shadows - Menu Shader Pipeline - Menu Color Theme - Thumbnails - Left Thumbnail - Thumbnails Vertical Disposition - Thumbnail Scale Factor - Thumbnail Upscaling Threshold - Ticker Text Animation - Ticker Text Speed - Smooth Ticker Text - Menu (Duplication/Shortcut to Settings > Driver > Menu) - Show Advanced Settings - Kiosk Mode - Navigation Wrap-Around - Pause Content When Menu is Active - Pause Content When Not Active - Resume Content after Using Save States - Resume Content after Changing Discs - Quit on Close Content - Menu Screensaver Timeout - Mouse Support - Touch Support - Threaded Tasks - UI Companion - Start UI Companion on Boot - Menu Bar - Desktop Menu (Restart Required) - Open Desktop Menu on Startup - Disable Desktop Composition - **AI Service** - AI Service Enabled - AI Service Output - AI Service URL - Pause During Translation - Source Language - Target Language - **Accessibility** - Accessibility Enable - Text-to-Speech Speed - **Power Management** - (Only available on certain devices) - **Achievements** - Achievements - Username - Password - Hardcore Mode - Leaderboards - Rich Presence - Achievement Badges - Test Unofficial Achievements - Unlock Sound - Verbose Mode - Automatic Screenshot - Start Active - **Network** - Publicly Announce Netplay - Use Relay Server - Server Address - Netplay TCP Port - Server Password - Server Spectate-Only Password - Netplay Spectator Mode - Allow Slave-Mode Clients - Disallow Non-Slave-Mode Clients - Netplay Stateless Mode - Netplay Check Frames - Input Latency Frames - Input Latency Frames Range - Netplay NAT Traversal - Digital Input Sharing - Analog Input Sharing - Request Device 1 - Request Device 2 - Request Device 3 - Request Device 4 - Request Device 5 - Request Device 6 - Request Device 7 - Request Device 8 - Request Device 9 - Request Device 10 - Request Device 11 - Request Device 12 - Request Device 13 - Request Device 14 - Request Device 15 - Request Device 16 - Network Commands - Network RetroPad - Network RetroPad Base Port - User 1 Network RetroPad - User 2 Network RetroPad - User 3 Network RetroPad - User 4 Network RetroPad - User 5 Network RetroPad - stdin Commands - On-Demand Thumbnail Downloads - **Updater** - Buildbot Cores URL - Buildbot Assets URL - Automatically Extract Downloaded Archive - Show Experimental Cores - Backup Cores When Updating - Core Backup History Size - **Playlists** - History - History Size - Favorites Size - Allow to Rename Entries - Allow to Remove Entries - Sort Playlists Alphabetically - Save Playlists Using Old Format - Compress Playlists - Show Associated Cores in Playlists - Show Playlist Sub-Labels - Playlist Sub-Label Runtime - 'Last Played' Date and Time Style - Fuzzy Archive Matching - Scan Without Core Match - Save Runtime Log (Per Core) - Save Runtime Log (Aggregate) - Portable Playlists - **Manage Playlists** - (Varies by user's playlists) - **User** - **Privacy** - (Varies by device) - **Accounts** - **RetroAchievements** - Username - Password - **YouTube** - YouTube Stream Key - **Twitch** - Twitch Stream Key - **Facebook Gaming** - Facebook Gaming Stream Key - Username - Language - **Directory** - System/BIOS - Downloads - Assets - Dynamic Backgrounds - Thumbnails - File Browser - Configs - Cores - Core Info - Databases - Cursor - Cheat Files - Video Filters - Audio Filters - Video Shaders - Recordings - Recording Configs - Overlays - Video Layouts - Screenshots - Input Autoconfig - Input Remaps - Playlists - Favorites Playlist - History Playlist - Images Playlist - Music Playlist - Videos Playlist - Runtime Logs - Save Files - Save States - Cache - System Event Logs ### Favorites ### History ### Images ### Music ### Videos ### Any Additional User-Created Playlists Appear Here ### Netplay - Host - Connect to Netplay Host - Network (Duplicate/Shortcut to Settings > Network) - Refresh Netplay Host List ### Import Content - Scan Directory - Scan File - **Manual Scan** - Content Directory - System Name - Custom System Name - Default Core - File Extensions - Scan Recursively - Scan Inside Archives - Arcade DAT File - Arcade DAT Filter - Overwrite Existing Playlist - Start Scan ### Explore - Search Name ... - Show All ## Quick Menu - Resume - Restart - Close Content - Take Screenshot - State Slot - Save State - Load State - Undo Load State - Undo Save State - Add to Favorites - Start Recording - Start Streaming - **Options** - (Varies by core) - **On-Screen Overlay** (Duplicate/Shortcut to Settings > On-Screen Display > On-Screen Overlay) - **Rewind** (Duplicate/Shortcut to Settings > Frame Throttle > Rewind) - **Latency** (Duplicate/Shortcut to Settings > Latency) - **Controls** - Load Remap File ... - Save Core Remap File - Save Content Directory Remap File - Save Game Remap File - **Turbo Fire** (Duplicate/Shortcut to Settings > Input > Turbo Fire) - **Port 1 Controls** - Device Type - Analog to Digital Type - (RetroPad to Core functions; varies by core) - **Port 2 Controls** - (Same as Port 1 Controls) - **Port 3 Controls** - (Same as Port 1 Controls) - **Port 4 Controls** - (Same as Port 1 Controls) - **Port 5 Controls** - (Same as Port 1 Controls) - (More or Fewer Ports based on Settings > Input > Maximum Users) - **Cheats** - Start or Continue Cheat Search - Load Cheat File (Replace) ... - Load Cheat File (Append) ... - Reload Game Specific Cheats - Save Cheat File As ... - Add New Cheat to Top - Add New Cheat to Bottom - Delete All Cheats - Auto-Apply Cheats During Game Load - Apply After Toggle - Apply Changes - **Shaders** - Video Shaders - Watch Shader Files for Changes - Remember Last Used Shader Directory - Load ... - **Save** - Simple Presets - Save Shader Preset As ... - Save Global Preset - Save Core Preset - Save Content Directory Preset - Save Game Preset - **Remove** - Apply Changes - **Shader Parameters** - (Varies by active shader preset) - **Shader Passes** - (Varies by active shader preset) - **Overrides** - Save Core Overrides - Save Content Directory Overrides - Save Game Overrides - **Information** - Name - File Path - Core - Runtime - Last Played - Download Thumbnails ================================================ FILE: docs/guides/xmb.md ================================================ # XMB (GUI) **XMB** was the default user interface for RetroArch, until it was succeeded by Ozone in RetroArch 1.7.6. It is based on Sony's "cross-media bar" GUI, most widely known from the PSP and PlayStation 3. ![XMB startup screen](../image/retroarch/xmb/main-menu.jpg) ## Menu Structure The top-level menus and playlists are displayed in a single "primary" row, running from left to right. For the selected row item, a submenu column will appear below it. ### Navigating the menus XMB is designed for use with a gamepad or keyboard. Press `left` or `right` to move along the primary row, and press `up` or `down` to scroll the column. The selected item in this column is always the first line under the primary row. The user can press `backspace` to go back a step. ## Input Content is controlled using a keyboard or gamepad, connected via USB or Bluetooth. See [Input and Controls](input-and-controls.md) ## Thumbnails By default, no thumbnails are displayed. Up to 2 can be enabled: The primary thumbnail will appear on the lower right side of the screen when a Playlist entry is selected. The secondary thumbnail will appear on the left. Press the `spacebar` key to view the thumbnails full-screen (press `spacebar` again to toggle the view off). Thumbnails can be enabled in `Settings> User Interface> Appearance`, toggling the `Primary Thumbnail` and/or `Secondary Thumbnail` option. Thumbnails can be boxart, a title screen screenshot, or a gameplay screenshot. ![XMB with 'Boxart' thumbnails enabled](./image/retroarch/xmb/thumbnails1.png) ## Themes XMB has a number of styles built-in. They can be changed in the `Settings > User Interface > Appearance` menu. * The background color can be changed: Scroll through `Color Theme` to select a color. * The animated background "wallpaper" can also be changed (`Shader Pipeline`), the default being a PlayStation-style animated ribbon. * XMB can even show different wallpapers depending on the playlist selected: [Follow this guide](https://github.com/libretro/Lakka-LibreELEC/wiki/Dynamic-Wallpapers) using [these files](https://github.com/libretro/retroarch-assets/tree/master/wallpapers). * XMB also has a selection of icon sets to choose from (`Icon Theme`). ![XMB with an alternative background color, background animation, and icon set](./image/retroarch/xmb/theme_alt.png) *XMB with an alternative background color, background animation, and icon set.* ================================================ FILE: docs/image/Button_Pack/Readme.txt ================================================ Hey there! Hope you make good use of this pack. You can use all these assets in any project you want to (be it commercial or not). All of the assets are in the public domain under Creative Commons 0 (CC0) In this pack you will find over 500 buttons including: Xbox 360 controller Xbox One controller Play Station 3 controller Play Station 4 controller Play Station Move PS Vita Vive Controller Oculus Controllers & Remote Wii Controller Wii U Controller Nintentdo Switch Steam Controller (Updated to commercial version) Ouya Keyboard and mouse buttons (Both in black and white including blanks) Directional arrows for thumb sticks and movement keys Touch Screen Gestures ---------------------------------- I am "Nicolae Berbece" (also known as Xelu), I founded "Those Awesome Guys" and made "Move or Die" which is out right now on Steam. You can contact me at nick@thoseawesomeguys.com Feel free to credit me in case you use anything in this pack, but don't worry, I won't mind if you don't. ;) Please share this pack with other fellow developers in need of such assets! In the spirit of good old chain mail, if you share this pack with 5 fellow devs, your game's steam review score will rise by 7% and a notable twitch streamer will pick it up for his stream. Keep making awesome things!!! ~Nick Here is a semi-updated list of games using these prompts: ---------------------------- Mega Man Legacy Postal 2 Postal Redux RWBY Heat Signature Turbo Dismount Fallen Legion 20XX Obduction Battle Chef Brigade Phantom Brigade Redirection Defender's Quest Roundabout Arena 3D Super Comboman Disc Jam Mayan Death Robots Sentris Unbox Induction Shadow Warrior 2 The Flock Deputy dangle Tumblestone Solbrain Knight of Darkness SSMP Distance Idarb Earthlock Everspace Pylon Rogue The Church in the darkness Sword n' Board ================================================ FILE: docs/image/core/genesis_plus_gx/bram.drawio ================================================ 7Z3dc6o6EMD/Gh/tEEIiPvb7TO/tnN56O2fmvnQQIjJF4gH8On/9DV8qIbRUQaPyorhAoPvbJLubhXbg7WT56BvT8TO1iNtRFWvZgXcdVcUAKOwrkqwSCcC9fiKxfcdKZRvBwPlDUmF6oj1zLBLkDgwpdUNnmhea1POIGeZkhu/TRf6wEXXzV50aNikIBqbhFqW/HCscJ1IdKRv5D+LY4+zKQEn3TIzs4FQQjA2LLrZE8L4Db31Kw2RrsrwlbqS9TC/JeQ8le9c35hMvrHLCX6+3q/n8wR6R/3T6Ch4H5njWxUkrc8OdpX9wR8Uua+9mRFmz7K7DVaoK/HtGsx3dIAZ1zQ4AaLrc7GRbdvRtGn54NfQnWWvstpIGk92pRtZtq0w502jToyH7ulmMnZAMpoYZyRbMtJhsHE5c9guwzaFhftg+nXnWz1noOh5J5Zbhf/xkZzlhZG7KlYLW19rWU6q6OfFDstwSpXp7JHRCQn/FDkn3dqGeYU3tuAv62hVKRIstu0iPGm+bRHaqkZqivW5/Q4ttpMC+AU9vCF5gWu9vZ0RPQz2OHlSOT6/fIL37c6IHoYT0svmpEXxP54QP8EOnDPhUJMDHKdYIpolHMXKWhDV2MyW+wy5PfCZj12AuCHnZiLa1bLiO7bFtkyku3ree/JVY18E4ajD+EURK9+x/KQN1B5nAmcQuSfZ950xs9ie6zpB9GmbozMm75fjszmikhwdmLtbcugrmdm2jZR/lgKlIgAsJcKHGaInGypZWQgvlaXVVUe86KC4oGhtbXAkuIFvn0lpa5a4Hko4WaGmV0gLSDYWa2uIqw6X2pOtcsKVV6sarHC3l6LS0llYZLUXnh8L+0XG1IVc5Lk26zrV/ZphpRZDfGBDbYDtv2XnK24B9PBoTEmRtD/1NnqNa+oPpOMxbgk/YPRjD+IAI95Q6XhjrB9100F1kK7OQJveZMx2XjKKmInCOabjXqTiM7CRvNF2tLvKY81l00SSoKgL0amPoew2hf95Cf/928ehhTzr0SBRd1I3+6eXi0QNNPvSiSCWBYTlznk8dc8DDtlG8Xj9Hm4YflprAWiy4n9pv8RumKb6vszJYqOtcEl+Fotha6KPAxkxWFK59cw2mV8lHuTHMj9k0M9OLGKKwxhGHWBcRVw86SIlCvjqIF1yTCySuFRbqZCBeQ4XKl8Rjj+QCiYNCXYQExLGorIXTe7bmHTCluOQ6qvOKnYAoRndopDeP+tHtf7UcXo8jr3JqBEg0OeKDrnBnaE9HjUpfRjVWWG+RS40IIwnVuH+1ExL66fH4PVgFIZlEY3g0dsdHTwlz3JWhQy83yCx4cBoGIkOAh/TZdVGYyemdeFbaiVjHiSqUKvURYuUqeYuKqZhK9YlrRCnfXOMiPaRXeIls4HPPub/We9ZOQGe+SdJTNyottgZxofqt2Fpo+DYJC63FgNYK2KPWDdYQaF1GmTDIw9KEifwDVyrC8qApzljsCq8eE/gUf6XUiuRGwcYDNWcU63rWLZPI8oHbJqF/MvbsaRGiDD+n1UtdisNcahbDo5clAFghJLpUXojLTErBq61XrVwAKQOvdrH7UBFJnn1PEblHh133Alp5aNoufLULX1xSCupCkz3ouhdAFUqp5EpK8T1f68FKY36DYdEnKwt7dKpdslQ2mxQO3fnF99l2/rzVonznB6gYueGewGxxc1ZbIXQ79fwZp3U2ku6RPtO+bKzp7Bk+vSUELqaSYLTG6skpEUg35eFiHveqnize+eRwNcSVZVZO1zWHrYaqly9zr98PRqUHySXjj593xUW/ve1/xTKkHfuf1hS20yul4HWo9fCx557TK6SAGu8FHV+JJ+cF8Q95yqDEplazz3s6hXDHcRk2BrL1i3brkjv6RY1NsPrJTbCAK7LTcP/Yw5p+chMs/2YoGZR4chOsAuWzxPZJ73LPnAtKZVj+1kUrIS2vxOuRsBxIb8u3yp0bCcuB9P1f1No+UL/D2FpSXgIE8JsrL9HbWrDKz5/J0Fn7FWKRi+WlyDcZ9tsX4pXHBpqE/UsUYbWvGGn82d4DT4b2cEVeof7P30/j8Z8fv5fvAX3q7v92GShEf2+Y405WR6XYhEFhdxJ/0oXX4Z/tVkaOW15wdV5mwL9fStUE6QHRs6CNGcH+/f8Sk7YAq1dc/l3VCySbStsKQbbLKLs95d6TDWS7jLJb4rXYI4tja00g2c/NfwpKKhM3/3AJ3v8P ================================================ FILE: docs/index.md ================================================ --- template: home.html title: Home --- ================================================ FILE: docs/library/2048.md ================================================ # 2048 ## Background This is a port of 2048, a game, to libretro. #### How to start the 2048 core: - To start the 2048 core, go to RetroArch's main menu screen. Select 'Load Core', then '2048'. - Now, select 'Start Core'.
![](../image/core/2048/start.png)
The content should now start running! ### Author/License The 2048 game has been authored by - Gabriele Cirulli The libretro implementation was authored by - Higor Eurípedes The 2048 core is licensed under - [Public Domain](https://github.com/libretro/libretro-2048/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Features Frontend-level settings or features that the 2048 core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The 2048 core's internal core name is '2048' The 2048 core saves/loads to/from these directories. **Frontend's Save directory** - 2048.srm (Previous game sessions and hiscores) **Frontend's State directory** - 2048.state# (State) ### Geometry and timing - The 2048 core's core provided FPS is 60 - The 2048 core's core provided sample rate is 30000 Hz - The 2048 core's core provided aspect ratio is 1 ## Controllers The 2048 core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. - **RetroPad** - Joypad - RetroPad w/Analog - Joypad - There's no reason to switch to this. ### Controller tables #### Joypad | User 1 Remap descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | Pause | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | Up | ![](../image/retropad/retro_dpad_up.png) | | Down | ![](../image/retropad/retro_dpad_down.png) | | Left | ![](../image/retropad/retro_dpad_left.png) | | Right | ![](../image/retropad/retro_dpad_right.png) | ## External Links - [Official 2048 Website](https://gabrielecirulli.github.io/2048/) - [Official 2048 Github Repository](https://github.com/gabrielecirulli/2048) - [Libretro 2048 Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/2048_libretro.info) - [Libretro 2048 Github Repository](https://github.com/libretro/libretro-2048) - [Report Libretro 2048 Core Issues Here](https://github.com/libretro/libretro-2048/issues) ================================================ FILE: docs/library/3d_engine.md ================================================ # 3D Engine ## Contribute to this documentation In order to propose improvements to this document, [visit its corresponding source page on github](https://github.com/libretro/docs/tree/master/docs/library/3d_engine.md). Changes are proposed using "Pull Requests." ## Background A tech demo for libretro GL with additional features (camera/location/etc). ### Why use this core? Awaiting description. ### How to get and install the 3D Engine core: 1. Start up RetroArch. Inside the main menu, go to 'Online Updater'. 2. Just to make sure we have the latest info files, select 'Update Core Info Files'. Wait until this is done. Then, select 'Core Downloader'. 3. Browse through the list and select '3D Engine'. After this has finished downloading, the core should now be ready for use! #### How to start (after installation): 1. Go back to RetroArch's main menu screen. Select 'Load Content'. 2. Browse to the folder that contains the content you want to run. 3. Select the content that you want to run. 4. If you are asked which core to select, choose '3D Engine'. The content should now start running! ### Authors - [Team Libretro](https://www.libretro.com/) ## License A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). - [GPLv3](https://github.com/libretro/libretro-3dengine/blob/master/license) ## Extensions Content that can be loaded by the 3D Engine core have the following file extensions: - .png - .jpg - .mtl - .obj ## Features RetroArch features that the 3D Engine core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✕ | | Screenshots | ✔ | | Saves | ✕ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✕ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✔ | | Camera | ✔ | | Location | ✔ | | Subsystem | ✕ | | Softpatching | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | ### Directories The 3D Engine core's directory name is 'Libretro 3DEngine' ### Geometry and timing The 3D Engine core's internal FPS is 60.0. The 3D Engine core's internal sample rate is 30000.0 Hz. The 3D Engine core's core provided aspect ratio is (Ratio). ## Core options The 3D Engine core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Internal resolution** (**320x240**/360x480/480x272/512x384/512x512/640x240/640x448/640x480/720x576/800x600/960x720/1024x768/1024x1024/1280x720/1280x960/1600x1200/1920x1080/1920x1440/1920x1600/2048x1152/2048x1536/2048x2048/320x240)
Self explanatory.
- **Cube size** (**0**/1/2/4/8/16/32/64/128)
Awaiting description.
- **Cube stride** (2.0 to 8.0 in increments of 1.0. **2.0 is default**)
Awaiting description.
- **Camera enable** (**Off**/On)
Awaiting description.
- **Camera FB Type** (**texture/**/raw framebuffer)
Awaiting description.
- **Sensor enable** (**Off**/On)
Awaiting description.
- **Location enable** (**Off**/On)
Awaiting description.
- **Location camera control** (**Off**/On)
Awaiting description.
- **Discard hack enable** (**Off**/On)
Awaiting description.
- **Location position OSD** (**Off**/On)
Awaiting description.
## Controllers ### Device types The 3D Engine core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): #### User 1 device types - None - Doesn't disable input. - **RetroPad** - Joypad - RetroPad w/Analog - Joypad - **There is no reason to switch to this.** ### Controller tables #### Joypad and analog device type table | User 1 Remap descriptors | RetroPad Inputs | 3D Engine core inputs | |--------------------------|------------------------------------------------|------------------------------------------| | | ![](../image/retropad/retro_b.png) | Jump/Zoom-in | | | ![](../image/retropad/retro_dpad_up.png) | Move forwards | | | ![](../image/retropad/retro_dpad_down.png) | Move backwards | | | ![](../image/retropad/retro_dpad_left.png) | Turn left | | | ![](../image/retropad/retro_dpad_right.png) | Turn right | | | ![](../image/retropad/retro_a.png) | Zoom-out | | | ![](../image/retropad/retro_l1.png) | Move left | | | ![](../image/retropad/retro_r1.png) | Move right | | | ![](../image/retropad/retro_l2.png) | Adjust lighting | | | ![](../image/retropad/retro_r2.png) | Adjust lighting | | | ![](../image/retropad/retro_r3.png) | Adjust lighting | | | ![](../image/retropad/retro_left_stick.png) X | Move right or left/Rotate model | | | ![](../image/retropad/retro_left_stick.png) Y | Move forwards and backwards/Rotate model | | | ![](../image/retropad/retro_right_stick.png) X | Look right and left | | | ![](../image/retropad/retro_right_stick.png) Y | Look up and down/Zoom-in or Zoom-out | ## External Links - [Libretro 3D Engine Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/3dengine_libretro.info) - [Libretro 3D Engine Github Repository](https://github.com/libretro/libretro-3dengine) - [Report Libretro 3D Engine Core Issues Here](https://github.com/libretro/libretro-3dengine/issues) ================================================ FILE: docs/library/amiarcadia.md ================================================ # Arcadia 2001 / Interton VC 4000 (AmiArcadia) ## Background AmiArcadia is an emulator for Signetics 2650 CPU-based systems. It emulates the Emerson Arcadia 2001 and its many clones (Bandai, Grandstand, etc.), the Interton VC 4000 family (Voltmace, Rowtron, etc.), the Elektor TV Games Computer, and Zaccaria/Malzak coin-op arcade machines. The core automatically identifies known ROMs by CRC32 and configures the correct machine type, memory map, and game-specific settings. For unknown ROMs, use the "Machine" core option to select between Arcadia and Interton modes. ### Author/License The AmiArcadia core has been authored by - James Jacobs The AmiArcadia core is licensed under - Non-commercial A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the AmiArcadia core have the following file extensions: - .bin - .tvc ## Databases RetroArch database(s) that are associated with the AmiArcadia core: - [Elektor - TV Games Computer](https://github.com/libretro/libretro-database/blob/master/rdb/Elektor%20-%20TV%20Games%20Computer.rdb) - [Emerson - Arcadia 2001](https://github.com/libretro/libretro-database/blob/master/rdb/Emerson%20-%20Arcadia%202001.rdb) - [Interton - VC 4000](https://github.com/libretro/libretro-database/blob/master/rdb/Interton%20-%20VC%204000.rdb) ## BIOS The AmiArcadia core does not require any BIOS files. ## Features Frontend-level settings or features that the AmiArcadia core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✕ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The AmiArcadia core's library name is 'AmiArcadia' ### Geometry and timing - The AmiArcadia core's core provided FPS is 60 for NTSC and 50 for PAL - The AmiArcadia core's core provided sample rate is 11025 Hz - The AmiArcadia core's base width is 164 (home consoles) or 240 (coin-ops) - The AmiArcadia core's base height is 226 (NTSC) / 269 (PAL) for home consoles, or 240 for coin-ops - The AmiArcadia core's max width is 240 - The AmiArcadia core's max height is 269 ## Core options The AmiArcadia core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. - **Machine** [amiarcadia_machine] (**Arcadia**|Interton) Select the machine type for unknown ROMs. Known ROMs auto-detect the correct machine. Choose between Arcadia 2001 and Interton VC 4000 modes. - **Region** [amiarcadia_region] (**PAL**|NTSC) Select the video timing region. PAL runs at 50Hz, NTSC runs at 60Hz. - **Sprite Demultiplexing** [amiarcadia_demultiplex] (**enabled**|disabled) Reduces sprite flicker in games that multiplex sprites across frames. ## Joypad | RetroPad Inputs | Player 1/2 input descriptors | |------------------------------------------------|------------------------------| | ![](../image/retropad/retro_b.png) | Keypad 1 | | ![](../image/retropad/retro_y.png) | Keypad 4 | | ![](../image/retropad/retro_select.png) | Console A | | ![](../image/retropad/retro_start.png) | Console Start | | ![](../image/retropad/retro_dpad_up.png) | Paddle Up | | ![](../image/retropad/retro_dpad_down.png) | Paddle Down | | ![](../image/retropad/retro_dpad_left.png) | Paddle Left | | ![](../image/retropad/retro_dpad_right.png) | Paddle Right | | ![](../image/retropad/retro_a.png) | Keypad 2 (Fire) | | ![](../image/retropad/retro_x.png) | Keypad 5 | | ![](../image/retropad/retro_l1.png) | Console B (Coin for arcade) | | ![](../image/retropad/retro_r1.png) | Keypad 0 | | ![](../image/retropad/retro_l2.png) | Console Reset | | ![](../image/retropad/retro_r2.png) | Keypad Enter | | ![](../image/retropad/retro_l3.png) | Keypad Clear | | ![](../image/retropad/retro_r3.png) | Keypad 6 | | ![](../image/retropad/retro_left_stick.png) X | Paddle X (Analog) | | ![](../image/retropad/retro_left_stick.png) Y | Paddle Y (Analog) | | ![](../image/retropad/retro_right_stick.png) X | Keypad 1-9 (8-directional) | | ![](../image/retropad/retro_right_stick.png) Y | Keypad 1-9 (8-directional) | The right analog stick maps to keypad keys 1-9 (excluding 5) in 8 directions, matching the layout of the original keypad: ``` 7 8 9 ↖ ↑ ↗ 4 6 = ← → 1 2 3 ↙ ↓ ↘ ``` Console buttons (Start, A, B, Reset) are only active on Player 1. ## Keyboard Desktop keyboard input is supported for Player 1's keypad. Both the number row and numeric keypad are mapped. | RetroKeyboard Inputs | AmiArcadia Inputs | |------------------------------|-------------------| | Keyboard 0 / Numpad 0 | Keypad 0 | | Keyboard 1 / Numpad 1 | Keypad 1 | | Keyboard 2 / Numpad 2 | Keypad 2 | | Keyboard 3 / Numpad 3 | Keypad 3 | | Keyboard 4 / Numpad 4 | Keypad 4 | | Keyboard 5 / Numpad 5 | Keypad 5 | | Keyboard 6 / Numpad 6 | Keypad 6 | | Keyboard 7 / Numpad 7 | Keypad 7 | | Keyboard 8 / Numpad 8 | Keypad 8 | | Keyboard 9 / Numpad 9 | Keypad 9 | | Keyboard [ / * / Numpad * | Keypad Clear | | Keyboard ] / # / Numpad Enter | Keypad Enter | ## Compatibility The core identifies known ROMs by CRC32 and automatically configures the correct machine type and settings. The following systems are emulated: **Home Consoles** - Emerson Arcadia 2001 (and compatible systems: Bandai, Grandstand, etc.) - Interton VC 4000 (and compatible systems: Voltmace, Rowtron, etc.) - Elektor TV Games Computer **Arcade (Coin-op)** - Zaccaria (Astro Wars, Galaxia, Laser Battle, Lazarian) - Malzak (Malzak I & II) ## External Links - [Official AmiArcadia/WinArcadia Website](https://amigan.1emu.net/releases/) - [Libretro AmiArcadia Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/amiarcadia_libretro.info) - [Libretro AmiArcadia Github Repository](https://github.com/warmenhoven/amiarcadia) ================================================ FILE: docs/library/anarch.md ================================================ # Anarch ## Background Anarch is an extremely small, completely public domain, no-dependency, no-file, portable suckless anarcho-pacifist from-scratch 90s-style Doom clone that runs everywhere. The Anarch core has been authored by - [Miloslav Číž](https://codeberg.org/drummyfish) - [iyzsong](https://codeberg.org/iyzsong) The Anarch core is licensed under - [CC0](https://codeberg.org/iyzsong/anarch-libretro/src/branch/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Features Frontend-level settings or features that the RVVM core respects. | Feature | Supported | |-------------------|:---------:| | Restart | - | | Saves | ✔ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | - | | Multi-Mouse | - | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Geometry and timing - The Anarch core's core provided FPS is 60. - The Anarch core's core provided sample rate is 8000 Hz. - The Anarch core's base width is 700. - The Anarch core's base height is 512. - The Anarch core's max width is 700. - The Anarch core's max height is 512. - The Anarch core's core provided aspect ratio is 175/128. ## User 1 device types The Anarch core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): - **RetroPad** - Keyboard - Mouse ## Joypad | RetroPad Inputs | Anarch core inputs | |------------------------------------------------|--------------------------| | ![](../image/retropad/retro_b.png) | Button B | | ![](../image/retropad/retro_y.png) | Jump | | ![](../image/retropad/retro_select.png) | Menu | | ![](../image/retropad/retro_start.png) | Map | | ![](../image/retropad/retro_dpad_up.png) | Up | | ![](../image/retropad/retro_dpad_down.png) | Down | | ![](../image/retropad/retro_dpad_left.png) | Left | | ![](../image/retropad/retro_dpad_right.png) | Right | | ![](../image/retropad/retro_a.png) | Button A | | ![](../image/retropad/retro_x.png) | Button C | | ![](../image/retropad/retro_l1.png) | Previous Weapon | | ![](../image/retropad/retro_r1.png) | Next Weapon | ## Keyboard | RetroKeyboard Inputs | Anarch core inputs | |------------------------------|---------------------------| | Keyboard w | Up | | Keyboard s | Down | | Keyboard q | Left | | Keyboard e | Right | | Keyboard j | Button A | | Keyboard k | Button B | | Keyboard l | Button C | | Keyboard p | Next Weapon | | Keyboard f | Cycle Weapon | | Keyboard Left Control | Button A | | Keyboard Left Shift | Button B | | Keyboard Space | Jump | | Keyboard Tab | Map | | Keyboard Escape | Menu | ## Mouse | RetroMouse Inputs | Anarch core inputs | |-------------------------------------------------------|---------------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Movement | | ![](../image/retromouse/retro_left.png) Mouse 1 | Button A | | ![](../image/retromouse/retro_right.png) Mouse 2 | Toggle Freelook | | ![](../image/retromouse/retro_middle.png) Mouse 3 | Cycle Weapon | | Wheel Up | Previous Weapon | | Wheel Down | Next Weapon | ## External Links - [Game Manual](https://codeberg.org/iyzsong/anarch-libretro/raw/branch/master/media/manual.png) - [Anarch Repository](https://codeberg.org/iyzsong/anarch-libretro) - [Anarch Issues Here](https://codeberg.org/iyzsong/anarch-libretro/issues) ================================================ FILE: docs/library/ardens.md ================================================ # Ardens ## Background Ardens is a simulator for the Arduboy FX. The Ardens core has been authored by - [Peter Brown](https://github.com/tiberiusbrown) The Ardens core is licensed under - [MIT](https://github.com/tiberiusbrown/Ardens/blob/master/LICENSE.txt) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Requirements¶ None ## BIOS¶ The Ardens core does not feature BIOS use. ## Extensions Content that can be loaded by the Ardens core have the following file extensions: - `.hex` or `.arduboy` RetroArch database(s) that are associated with the Ardens core: - [`Arduboy Inc - Arduboy.rdb`](https://github.com/libretro/libretro-database/blob/master/rdb/Arduboy%20Inc%20-%20Arduboy.rdb) ## Features Frontend-level settings or features that the Ardens core respects: | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | - | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Geometry and timing - The Ardens core's core provided FPS is 60 - The Ardens core's base width is 128 - The Ardens core's base height is 64 - The Ardens core's max width is 128 - The Ardens core's max height is 64 ## User 1 device types The Ardens core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): - None - Doesn't disable input. - **RetroPad** - RetroPad w/Analog ## Joypad | RetroPad Inputs | User 1 input descriptors | |------------------------------------------------|--------------------------| | ![](../image/retropad/retro_b.png) | Button B | | ![](../image/retropad/retro_dpad_up.png) | Up | | ![](../image/retropad/retro_dpad_down.png) | Down | | ![](../image/retropad/retro_dpad_left.png) | Left | | ![](../image/retropad/retro_dpad_right.png) | Right | | ![](../image/retropad/retro_a.png) | Button A | ## External Links - [Official Ardens Website](https://github.com/tiberiusbrown/Ardens) - [Libretro Ardens Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/ardens_libretro.info) - [Report Libretro Ardens Core Issues Here](https://github.com/tiberiusbrown/Ardens/issues) ================================================ FILE: docs/library/atari800.md ================================================ # Atari 8-bit computer systems and 5200 (Atari800) ## Background Atari 8-bit computer systems (400, 800, 600 XL, 800XL, 130XE) and 5200 game console emulator. The Atari800 core has been authored by - Petr Stehlik The Atari800 core is licensed under - [GPLv2](https://github.com/atari800/atari800/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Atari800 core have the following file extensions: - .xfd - .atr - .atx - .cdm - .cas - .bin - .a52 - .xex - .zip ## Databases RetroArch database(s) that are associated with the Atari800 core: - [Atari - 5200](https://github.com/libretro/libretro-database/blob/master/rdb/Atari%20-%205200.rdb) ## BIOS Required or optional firmware files go in RetroArch's system directory. | Filename | Description | md5sum | |:-------------:|:--------------------------------------:|:--------------------------------:| | 5200.rom | 5200 BIOS - Required | 281f20ea4320404ec820fb7ec0693b38 | | ATARIXL.ROM | Atari XL/XE OS BIOS - Required | 06daac977823773a3eea3422fd26a703 | | ATARIBAS.ROM | BASIC interpreter BIOS - Required | 0bac0c6a50104045d902df4503a4c30b | | ATARIOSA.ROM | Atari 400/800 PAL BIOS - Required | eb1f32f5d9f382db1bbfb8d7f9cb343a | | ATARIOSB.ROM | BIOS for Atari 400/800 NTSC - Required | a3e8d617c95d08031fe1b20d541434b2 | ## Features | Feature | Supported | |-------------------|:---------:| | Restart | ✕ | | Screenshots | ✔ | | Saves | - | | States | - | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | - | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | Softpatching | ✕ | | Disk Control | ✕ | | Username | ✕ | | Crop Overscan (in RetroArch's Video settings) | ✕ | ### Directories The Atari800 core's directory name is 'Atari800' Atari800 config settings are saved/loaded to and from .atari800.cfg in RetroArch's home directory (where RetroArch.exe is in Windows). - .atari800.cfg (Config) RetroArch.exe directory - .atari800.cfg (config) - .atari000.wav in exe directory (startup noise?) - .atari000.pcx in exe directory (screenshot) ### Core provided aspect ratio Atari800's core provided aspect ratio is 4/3. ### Usage Make sure you have the appropriate system files in RetroArch's system directory. Then, load a content file. The Atari800 core should boot to the 'Atari Computer - Memo Pad' screen. The Atari800 core will generate a '.atari800.cfg' config file in RetroArch's home directory and will add the required BIOS files it detects in the system directory to the config file. Now you can manually select what Atari system you want to emulate through the 'Atari System' core option. Finally, you can load any content files compatible with the system chosen through RetroArch's Load Content menu. !!! attention You can set per-game core option settings by creating a game-options file through RetroArch's Core Options menu. Alternatively, you can manually configure how the Atari800 will look for and handle BIOS files. While the Atari800 core is running, you can press F1 to get into the internal emulator menu. There - emulator configuration, system rom settings. From there, You can go to the 'Emulator Configuration' section and then the System ROM settings section to configure BIOS options. (Press Enter to confirm menu selections and press Escape to go back a menu) Then press Escape a few times to go back to the 'Emulator Configuration' section and select Save Configuration File or alternatively change Save configuration file on exit from no to yes Then you can exit the emulator by pressing F9 and then try the game again or press Shift+F5 to reboot the game. ## Core options The Atari800 core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Atari System** (**400/800 (OS B)**/800XL (64K)/130XE (128K)/5200)
Choose what Atari System to emulate.
- **Video Standard** (**NTSC**/PAL)
Awaiting description.
- **Internal BASIC (hold OPTION on boot)** (**Off**/On)
Awaiting description.
- **SIO Acceleration** (**Off**/On)
Awaiting description.
- **Boot from Cassette** (**Off**/On)
Awaiting description.
- **Hi-Res Artifacting** (**Off**/On)
Awaiting description.
- **Autodetect A5200 CartType** (**Off**/On)
Awaiting description.
- **Joy hack A5200 for robotron** (**Off**/On)
Awaiting description.
- **Internal resolution** (**336x240**/320x240/384x240/384x272/384x288/400x300)
Awaiting description.
- **Retroarch Keyboard type** (**poll**/callback)
Awaiting description.
## Controllers ### Device types The Atari800 core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): #### User 1 - 2 device types - None - Input disabled. - **RetroPad** - Joypad - Don't use this, switch to ATARI Joystick for joypad usage. - ATARI Joystick - Joypad - ATARI Keyboard - Keyboard - For keyboard usage ### Controller tables #### Joypad and analog device type table | User 1 Remap descriptors | RetroPad Inputs | ATARI Joystick | |--------------------------|------------------------------------------------|-------------------------| | B | ![](../image/retropad/retro_b.png) | KEY RETURN | | Y | ![](../image/retropad/retro_y.png) | VKBD ON/OFF | | Select | ![](../image/retropad/retro_select.png) | CONSOL_SELECT | | Start | ![](../image/retropad/retro_start.png) | CONSOL_START | | Up | ![](../image/retropad/retro_dpad_up.png) | Up | | Down | ![](../image/retropad/retro_dpad_down.png) | Down | | Left | ![](../image/retropad/retro_dpad_left.png) | Left | | Right | ![](../image/retropad/retro_dpad_right.png) | Right | | A | ![](../image/retropad/retro_a.png) | FIRE1/KEY RETURN IN GUI | | X | ![](../image/retropad/retro_x.png) | FIRE2/KEY ESCAPE IN GUI | | L | ![](../image/retropad/retro_l1.png) | CONSOLE_OPTION | | R | ![](../image/retropad/retro_r1.png) | TOGGLE_UI | | L2 | ![](../image/retropad/retro_l2.png) | KEY SPACE | | R2 | ![](../image/retropad/retro_r2.png) | KEY ESCAPE | | L3 | ![](../image/retropad/retro_l3.png) | | | R3 | ![](../image/retropad/retro_r3.png) | | #### Keyboard device type table | User # input descriptors | | ATARI Keyboard | |-------------------------------|-------------------------------|----------------------------| | N/A | Keyboard Numpad 2 | Down | | N/A | Keyboard Numpad 4 | Left | | N/A | Keyboard Numpad 6 | Right | | N/A | Keyboard Numpad 8 | Up | | N/A | Keyboard Up | Up | | N/A | Keyboard Down | Down | | N/A | Keyboard Right | Right | | N/A | Keyboard Left | Left | | N/A | Keyboard F1 | Built in UI | | N/A | Keyboard F2 | Option key | | N/A | Keyboard F3 | Select key | | N/A | Keyboard F4 | Start key | | N/A | Keyboard F5 | Reset key | | N/A | Keyboard F6 | Help key (XL/XE only) | | N/A | Keyboard F7 | Break key | | N/A | Keyboard F8 | Enter monitor | | N/A | Keyboard F9 | Exit emulator | | N/A | Keyboard F10 | Save screenshot | | N/A | Keyboard Right Control | Fire | | N/A | Keyboard Shift + F5 | Reboot | | N/A | Keyboard Shift + F10 | Save interlaced screenshot | | N/A | Keyboard Alt + R | Run Atari program | | N/A | Keyboard Alt + D | Disk management | | N/A | Keyboard Alt + C | Cartridge management | | N/A | Keyboard Alt + Y | Select system | | N/A | Keyboard Alt + O | Sound settings | | N/A | Keyboard Alt + W | Sound recording start/stop | | N/A | Keyboard Alt + S | Save state file | | N/A | Keyboard Alt + L | Load state file | | N/A | Keyboard Alt + A | About the emulator | ## External Links - [Libretro Atari800 Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/atari800_libretro.info) - [Libretro Atari800 Github Repository](https://github.com/libretro/libretro-atari800) - [Report Libretro Atari800 Core Issues Here](https://github.com/libretro/libretro-atari800/issues) - [Official Atari800 Website](https://atari800.github.io/) - [Official Atari800 Github Repository](https://github.com/atari800/atari800) ================================================ FILE: docs/library/b2.md ================================================ # Acorn - BBC Micro (b2-libretro) ## Background Emulate the BBC Micro and Master, a series of microcomputers designed and built by Acorn Computers Limited in the 1980s for the Computer Literacy Project of the BBC. The b2-libretro core has been authored by: - Tom Seddon (b2) - Zoltan Balogh (libretro core specific modifications) The b2 core is licensed under [GPL v3](https://github.com/zoltanvb/b2-libretro#licence). A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Requirements No special requirements. To be tested yet on low end platforms. ## Extensions Content that can be loaded by the b2 core have the following file extensions: - `.ssd/.dsd` - Floppy disk image RetroArch database(s) that are associated with the b2 core: - None yet ## Features Frontend-level settings or features that the b2 core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✕ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | - | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✔ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Directories No additional directories used, only content disk image is needed. ## Geometry and timing - The b2 core's core provided FPS is 50 - The b2 core's core provided sample rate is 250 kHz (to be optimized) - The b2 core's base width is 768 - The b2 core's base height is 288 - The b2 core's max width is 768 - The b2 core's max height is 576 (interlace mode) - The b2 core's core provided aspect ratio is 4:3 ## Usage Load any supported content file. Content type will be autodetected, and if possible, started: - If disk image name contains an executable file name in brackets (such as `[CHUCKIE]`), a `CHAIN` command will be issued shortly after initial booting - If disk image name does not contain such indication, Shift key press will be simulated during boot to trigger autoboot function In case of multi-disk games, use the Disk Control menu to add the subsequent images and switch between them. For BBC Master games, set emulated machine type to Master, and close the core, then re-open again with the content. ## Core options The b2 core has the following option(s) that can be tweaked from the core options menu. - Emulated machine - `B/Acorn 1770` - `B/Watford 1770 (DDB2)` - `B/Watford 1770 (DDB3)` - `B/Opus 1770` - `B/Opus CHALLENGER 256K` - `B/Opus CHALLENGER 512K` - `B+` - `B+128` - `Master 128 (MOS 3.20)` - Autoboot (on|off) - Keyboard assignments for each RetroPad button ## Joypad mapping The analogue joysticks are mapped to the left analog stick and face button A for RetroArch player 1 and 2 slots. Joypad is fully assignable to keyboard keys in core options. ## Keyboard Keyboard layout of the BBC Master (BBC Micro is the same, apart from cursor key arrangement and the lack of keypad): ![](../image/core/b2/bbc-master-keyboard.png) Keep in mind that certain characters will appear differently in the default Mode 7 prompt, same way as on the original machine. By changing to `MODE 6` the font display can be "fixed". Most mappings are straightforward positionally from an ISO UK keyboard: - Dark green: natural mapping, both position and function matches nicely - Light green: either position or function is slightly different - Yellow: function is different - Red: extra mapping - Dark grey: keys intentionally reserved for RetroArch / OS functions ![](../image/core/b2/iso-mapping-for-bbc-master.png) Exceptions are marked in the following table: | RetroKeyboard Inputs | BBC Micro/Master keyboard input | |------------------------------|---------------------------| | Keyboard F10 | f0 | | Keyboard F11 | Break | | Keyboard Pause | Break | | Keyboard Backspace | Delete | | Keyboard Backquote ` | Escape (alternative mapping) | | Keyboard Equals = | ^ (caret) | | Keyboard Oem 102 | \\ (backslash) | | Keyboard Home | \\ (alternative mapping) | | Keyboard Backspace | Delete | | Keyboard Left Bracket [ | @ (at) | | Keyboard Right Bracket ] | [ (left bracket) | | Keyboard End | _ (underline) | | Keyboard Quote ' | : (colon) | | Keyboard Backslash \ | ] (right bracket) (shown as # in ISO map) | | Keyboard Delete | Delete | | Keyboard PgUp | Caps Lock | | Keyboard PgDn | Shift Lock | | Keyboard NumLock | Shift Lock | | Keyboard Insert | Copy | | --- (no PC keyboard mapping) | Numpad , (comma) | | --- (no PC keyboard mapping) | Numpad # | | --- (no PC keyboard mapping) | Numpad Delete | If there is a need to press those 3 keys that have no mapping, use core options to map them to a RetroPad button. ## External Links - [Official b2-libretro core repository](https://github.com/zoltanvb/b2-libretro) - [Libretro b2 Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/b2_libretro.info) - [Report Libretro b2 Core Issues Here](https://github.com/zoltanvb/b2-libretro/issues) - [Original b2 Implementation](https://github.com/tom-seddon/b2) - [Complete BBC Micro Games Archive](https://www.bbcmicro.co.uk/) - [Stardot forums](https://www.stardot.org.uk/forums/) - BBC Micro community ================================================ FILE: docs/library/beetle_bsnes.md ================================================ # Nintendo - SNES / Famicom (Beetle bsnes) ## Background Standalone port of Mednafen bSNES to libretro, itself a old fork of bsnes 0.59. This core exists as a side effect of porting/forking mednafen for its other cores in the past. There's no reason to use this core now that there's other more compatible and faster SNES cores. ### Author/License The Beetle bsnes core has been authored by - byuu - [Mednafen Team](https://mednafen.github.io/) The Beetle bsnes core is licensed under - [GPLv2](https://github.com/libretro/beetle-bsnes-libretro/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Beetle bsnes core have the following file extensions: - .smc - .fig - .bs - .st - .sfc ## Databases RetroArch database(s) that are associated with the Beetle bsnes core: - [Nintendo - Super Nintendo Entertainment System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System.rdb) - [Nintendo - Super Nintendo Entertainment System Hacks](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System%20Hacks.rdb) - [Nintendo - Sufami Turbo](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Sufami%20Turbo.rdb) ## Features Frontend-level settings or features that the Beetle bsnes core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✕ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✔ | | LEDs | ✕ | ### Directories The Beetle bsnes core's internal core name is 'Mednafen bSNES' The Beetle bsnes core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.srm (Cartridge battery save) - 'content-name'.rtc (Real time clock save) **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The Beetle bsnes core's core provided FPS is 60.10 - The Beetle bsnes core's core provided sample rate is 44100 Hz - The Beetle bsnes core's core provided aspect ratio is 4/3 ## Controllers The Beetle bsnes core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 - 2 device types - None - Doesn't disable input - **RetroPad** - Joypad - RetroPad w/Analog - Joypad - There's no reason to switch to this. ### Controller tables #### Joypad ![](../image/controller/snes.png) | RetroPad Inputs | Beetle bsnes Inputs | |----------------------------------------------|---------------------------| | ![](../image/retropad/retro_b.png) | B | | ![](../image/retropad/retro_y.png) | Y | | ![](../image/retropad/retro_select.png) | Select | | ![](../image/retropad/retro_start.png) | Start | | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | | ![](../image/retropad/retro_a.png) | A | | ![](../image/retropad/retro_x.png) | X | | ![](../image/retropad/retro_l1.png) | L | | ![](../image/retropad/retro_r1.png) | R | ## External Links - [Official Mednafen Website](https://mednafen.github.io/) - [Official Mednafen Downloads](https://mednafen.github.io/releases/) - [Libretro Beetle bsnes Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mednafen_snes_libretro.info) - [Libretro Beetle bsnes Github Repository](https://github.com/libretro/beetle-bsnes-libretro) - [Report Libretro Beetle bsnes Core Issues Here](https://github.com/libretro/beetle-bsnes-libretro/issues) ### See also #### Nintendo - Sufami Turbo - [Nintendo - SNES / Famicom (bsnes-jg)](bsnes-jg.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) #### Nintendo - Super Nintendo Entertainment System (+Hacks) - [Nintendo - SNES / Famicom (bsnes-jg)](bsnes-jg.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (higan Accuracy)](higan_accuracy.md) - [Nintendo - SNES / Famicom (nSide Balanced)](nside_balanced.md) - [Nintendo - SNES / Famicom (Mesen-S)](mesen-s.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) ================================================ FILE: docs/library/beetle_cygne.md ================================================ # Bandai - WonderSwan/Color (Beetle Cygne) ## Background Standalone port of Mednafen WonderSwan to libretro, itself a fork of Cygne. ### Author/License The Beetle Cygne core has been authored by - Dox - [Mednafen Team](https://mednafen.github.io/) The Beetle Cygne core is licensed under - [GPLv2](https://github.com/libretro/beetle-wswan-libretro/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Beetle Cygne core have the following file extensions: - .ws - .wsc - .pc2 (Benesse Pocket Challenge v2 files) ## Databases RetroArch database(s) that are associated with the Beetle Cygne core: - [Bandai - WonderSwan](https://github.com/libretro/libretro-database/blob/master/rdb/Bandai%20-%20WonderSwan.rdb) - [Bandai - WonderSwan Color](https://github.com/libretro/libretro-database/blob/master/rdb/Bandai%20-%20WonderSwan%20Color.rdb) ## Features Frontend-level settings or features that the Beetle Cygne core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ (not link-cable emulation) | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Beetle Cygne core's internal core name is 'Beetle WonderSwan' The Beetle Cygne core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.srm (Cartridge backup save) **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The Beetle Cygne core's core provided FPS is 75.47 - The Beetle Cygne core's core provided sample rate is 44100 Hz - The Beetle Cygne core's core provided aspect ratio is 14/9 ## Controllers The Beetle Cygne core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. - **RetroPad** - Joypad - RetroPad w/Analog - There is no reason to switch to this. ### Controller tables #### Joypad | User 1 Remap descriptors | RetroPad Inputs | |------------------------------|-------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Rotate screen + active D-Pad | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | X Cursor Up | ![](../image/retropad/retro_dpad_up.png) | | X Cursor Down | ![](../image/retropad/retro_dpad_down.png) | | X Cursor Left | ![](../image/retropad/retro_dpad_left.png) | | X Cursor Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | Y Cursor Left | ![](../image/retropad/retro_l1.png) | | Y Cursor Right | ![](../image/retropad/retro_r1.png) | | Y Cursor Down | ![](../image/retropad/retro_l2.png) | | Y Cursor Up | ![](../image/retropad/retro_r2.png) | ## Compatibility | Game | Issue | |-----------|------------------------------------------------------------------------------| | Tonpuusou | Title screen announcer voice missing. Softlocks after picking a menu option. | ## External Links - [Official Mednafen Website](https://mednafen.github.io/) - [Official Mednafen Downloads](https://mednafen.github.io/releases/) - [Libretro Beetle Cygne Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mednafen_wswan_libretro.info) - [Libretro Beetle Cygne Github Repository](https://github.com/libretro/beetle-wswan-libretro) - [Report Libretro Beetle Cygne Core Issues Here](https://github.com/libretro/beetle-wswan-libretro/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0IdmXFd9hF4bXjsk_zKwT8Yz) ================================================ FILE: docs/library/beetle_gba.md ================================================ # Nintendo - Game Boy Advance (Beetle GBA) ## Background Standalone port of Mednafen GBA to libretro, itself a fork of VBA-M, itself a fork of Visual Boy Advance. ### Author/License The Beetle GBA core has been authored by - Forgotten - [Mednafen Team](https://mednafen.github.io/) The Beetle GBA core is licensed under - [GPLv2](https://github.com/libretro/beetle-gba-libretro/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Beetle GBA core have the following file extensions: - .gba - .agb - .bin ## Databases RetroArch database(s) that are associated with the Beetle GBA core: - [Nintendo - Game Boy Advance](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Game%20Boy%20Advance.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:------------:|:--------------------------------:|:--------------------------------:| | gba_bios.bin | Game Boy Advance BIOS - Optional | a860e8c0b6d573d191e4ec7db1b1e4f6 | ## Features Frontend-level settings or features that the Beetle GBA core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✕ | | [RetroArch SaveRAM Autosave Interval support](https://github.com/libretro/RetroArch/issues/16323#issuecomment-1977792161) | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✔ | | LEDs | ✕ | ### Directories The Beetle GBA core's internal core name is 'Beetle GBA' The Beetle GBA core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.'ROM MD5'.sav (SRAM) - 'content-name'.'ROM MD5'.eep (EEPROM) **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The Beetle GBA core's core provided FPS is 59.73 - The Beetle GBA core's core provided sample rate is 44100 Hz - The Beetle GBA core's core provided aspect ratio is 3/2 ## Core options The Beetle GBA core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **HLE bios emulation** [gba_hle] (**enabled**/disabled) Self-explanatory. When set to off, a Game Boy Advance BIOS is required. ## Controllers The Beetle GBA core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. - **RetroPad** - Joypad - RetroPad w/Analog - Joypad - There's no reason to switch to this. ### Controller tables #### Joypad ![](../image/controller/gba.png) | User 1 Remap descriptors | RetroPad Inputs | |--------------------------|------------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | ## External Links - [Official Mednafen Website](https://mednafen.github.io/) - [Official Mednafen Downloads](https://mednafen.github.io/releases/) - [Libretro Beetle GBA Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mednafen_gba_libretro.info) - [Libretro Beetle GBA Github Repository](https://github.com/libretro/beetle-gba-libretro) - [Report Libretro Beetle GBA Core Issues Here](https://github.com/libretro/beetle-gba-libretro/issues) ### See also #### Nintendo - Game Boy Advance - [Nintendo - Game Boy Advance (gpSP)](gpsp.md) - [Nintendo - Game Boy Advance (Meteor)](meteor.md) - [Nintendo - Game Boy Advance (mGBA)](mgba.md) - [Nintendo - Game Boy Advance (VBA-M)](vba_m.md) - [Nintendo - Game Boy Advance (VBA Next)](vba_next.md) - [Nintendo - Game Boy Advance (TempGBA)](tempgba.md) ================================================ FILE: docs/library/beetle_lynx.md ================================================ # Atari - Lynx (Beetle Lynx) ## Background Beetle Lynx is an Atari Lynx video game system emulator that can be used as a libretro core. Specifically it's a port of Mednafen Lynx which is a fork of Handy. ### Author/License The Beetle Lynx core has been authored by - K. Wilkins - [Mednafen Team](https://mednafen.github.io/) The Beetle Lynx core is licensed under - [zlib](https://github.com/libretro/beetle-lynx-libretro/blob/master/mednafen/lynx/license.txt), [GPLv2](https://github.com/libretro/beetle-lynx-libretro/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Beetle Lynx core have the following file extensions: - .lnx - .o ## Databases RetroArch database(s) that are associated with the Beetle Lynx core: - [Atari - Lynx](https://github.com/libretro/libretro-database/blob/master/rdb/Atari%20-%20Lynx.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:-------------:|:--------------------------:|:--------------------------------:| | lynxboot.img | Lynx Boot Image - Required | fcd403db69f54290b51035d82f835e7b | ## Features Frontend-level settings or features that the Beetle Lynx core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✕ | | States | ✔ | | Rewind | ✔ | | Netplay (State based) | ✔ (not link-cable emulation) | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | Cheats (Cheats menu) | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✔ | | LEDs | ✕ | ### Directories The Beetle Lynx core's directory name is 'Beetle Lynx' The Beetle Lynx core saves/loads to/from these directories. **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The Beetle Lynx core's core provided FPS is 75 - The Beetle Lynx core's core provided sample rate is 44100 Hz - The Beetle Lynx core's core provided aspect ratio is 80/51 ## Loading content Beetle Lynx supports Lynx headered roms and non-headered roms. It also supports homebrews in *.o extensions. ## Core options The Beetle Lynx core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Auto-rotate Screen** [lynx_rot_screen] (**enabled**/disabled) Virtually rotates the screen orientation and keymaps automatically for known games. When disabled, screen rotation is manually adjusted by pressing the SELECT button. ## Controllers The Beetle Lynx core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. - **RetroPad** - Joypad - RetroPad w/Analog - Joypad - There's no reason to switch to this. ### Controller tables ![](../image/controller/lynx.png) #### Joypad | User 1 Remap descriptors | RetroPad Inputs | Beetle Lynx core inputs | |--------------------------|------------------------------------------------|--------------------------| | | ![](../image/retropad/retro_b.png) | B | | | ![](../image/retropad/retro_start.png) | Pause | | | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | | | ![](../image/retropad/retro_a.png) | A | | | ![](../image/retropad/retro_l1.png) | Option 1 | | | ![](../image/retropad/retro_r1.png) | Option 2 | Supported combinations * Option 1 + Pause = Flips Screen * Option 2 + Pause = Restarts game ## Compatibility | Game | Issue | |------------------|-------------------------------------------------------------------------| | RoadBlasters | Graphics glitches. Minor flickering and glitches after starting a race. | ## External Links - [Official Mednafen Website](https://mednafen.github.io/) - [Official Mednafen Downloads](https://mednafen.github.io/releases/) - [Libretro Beetle Lynx Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mednafen_lynx_libretro.info) - [Libretro Beetle Lynx Github Repository](https://github.com/libretro/beetle-lynx-libretro) - [Report Libretro Beetle Lynx Core Issues Here](https://github.com/libretro/beetle-lynx-libretro/issues) ### See also #### Atari - Lynx - [Atari - Lynx (Handy)](handy.md) - [Atari - Lynx (Holani)](holani.md) ================================================ FILE: docs/library/beetle_neopop.md ================================================ # SNK - Neo Geo Pocket / Color (Beetle NeoPop) ## Background Beetle/Mednafen NGP is a SNK Neo Geo Pocket (Color) video game system emulator based on NeoPop. ### Author/License The Beetle NeoPop core has been authored by - neopop_uk - [Mednafen Team](https://mednafen.github.io/) The Beetle NeoPop core is licensed under - [GPLv2](https://github.com/libretro/beetle-ngp-libretro/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Beetle NeoPop core have the following file extensions: - .ngp - .ngc ## Databases RetroArch database(s) that are associated with the Beetle Neopop core: - [SNK - Neo Geo Pocket](https://github.com/libretro/libretro-database/blob/master/rdb/SNK%20-%20Neo%20Geo%20Pocket.rdb) - [SNK - Neo Geo Pocket Color](https://github.com/libretro/libretro-database/blob/master/rdb/SNK%20-%20Neo%20Geo%20Pocket%20Color.rdb) ## Features Frontend-level settings or features that the Beetle NeoPop core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ (not link-cable emulation) | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Beetle NeoPop core's internal core name is 'Beetle NeoPop' The Beetle NeoPop core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.flash (Cartrtidge battery save) **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The Beetle NeoPop core's core provided FPS is 60 - The Beetle NeoPop core's core provided sample rate is 44100 Hz - The Beetle NeoPop core's core provided aspect ratio is 20/19 ## Core options The Beetle NeoPop core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Language (restart)** [ngp_language] (**english**/japanese) Choose the system language of the BIOS. ## Controllers The Beetle NeoPop core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. - **RetroPad** - Joypad - RetroPad w/Analog - Joypad - There's no reason to switch to this. ### Controller tables #### Joypad ![](../image/controller/ngp.png) | User 1 Remap descriptors | RetroPad Inputs | |--------------------------|------------------------------------------------| | A | ![](../image/retropad/retro_b.png) | | Option | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | B | ![](../image/retropad/retro_a.png) | ## External Links - [Official Mednafen Website](https://mednafen.github.io/) - [Official Mednafen Downloads](https://mednafen.github.io/releases/) - [Libretro Beetle NeoPop Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mednafen_ngp_libretro.info) - [Libretro Beetle NeoPop Github Repository](https://github.com/libretro/beetle-ngp-libretro) - [Report Libretro Beetle NeoPop Core Issues Here](https://github.com/libretro/beetle-ngp-libretro/issues) ================================================ FILE: docs/library/beetle_pc_fx.md ================================================ # NEC - PC-FX (Beetle PC-FX) ## Background Beetle PC-FX is a port of Mednafen PC-FX video game system emulator for the NEC PC-FX. ### Author/License The Beetle PC-FX core has been authored by - [Mednafen Team](https://mednafen.github.io/) The Beetle PC-FX core is licensed under - [GPLv2](https://github.com/libretro/beetle-pcfx-libretro/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Beetle PC-FX core have the following file extensions: - .cue - .ccd - .toc - .chd ## Databases RetroArch database(s) that are associated with the Beetle PC-FX core: - [NEC - PC-FX](https://github.com/libretro/libretro-database/blob/master/rdb/NEC%20-%20PC-FX.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:-------------:|:----------------------------------------:|:--------------------------------:| | pcfx.rom | PC-FX BIOS v1.00 - 2 Sep 1994 - Required | 08e36edbea28a017f79f8d4f7ff9b6d7 | ## Features Frontend-level settings or features that the Beetle PC-FX core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✔ | | LEDs | ✕ | ### Directories The Beetle PC-FX core's internal core name is 'Beetle PC-FX' The Beetle PC-FX core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.srm (Save) **Frontend's State directory** - 'content-name-.state# (State) ### Geometry and timing - The Beetle PC-FX core's core provided FPS is 60 - The Beetle PC-FX core's core provided sample rate is 44100 Hz - The Beetle PC-FX core's core provided aspect ratio is 4/3 ### Loading PC-FX content Beetle PC-FX needs a cue-sheet that points to an image file. A cue sheet, or cue file, is a metadata file which describes how the tracks of a CD or DVD are laid out. If you have e.g. `foo.bin`, you should create a text file and save it as `foo.cue`. If you're playing a single-track Saturn game, then the cue file contents should look like this: `foobin.cue` ``` FILE "foo.bin" BINARY TRACK 01 MODE1/2352 INDEX 01 00:00:00 ``` After that, you can load the `foo.cue` file in RetroArch with the Beetle PC-FX core. !!! attention Certain PC-FX games are multi-track, so their .cue files might be more complicated. ## Core options The Beetle PC-FX core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **High Dotclock Width (Restart)** [pcfx_high_dotclock_width] (**1024**/256/341) Emulated width for 7.16MHz dot-clock mode. Lower values are faster, but will cause some degree of pixel distortion. - **Suppress Channel Reset Clicks (Restart)** [pcfx_suppress_channel_reset_clicks] (**enabled**/disabled) Hack to suppress clicks caused by forced channel resets. - **Emulate Buggy Codec (Restart)** [pcfx_emulate_buggy_codec] (**disabled**/enabled) Hack that emulates the codec a buggy ADPCM encoder used for some games' ADPCM. - **Sound Quality (Restart)** [pcfx_resamp_quality] (**3**/4/5/0/1/2) Higher values correspond to better SNR and better preservation of higher frequencies("brightness"), at the cost of increased computational complexity and a negligible increase in latency. - **Chroma channel bilinear interpolation (Restart)** [pcfx_rainbow_chromaip] (**disabled**/enabled) Enable bilinear interpolation on the chroma channel of RAINBOW YUV output. Enabling it may cause graphical glitches with some games. - **No Sprite Limit (Restart)** [pcfx_nospritelimit] (**disabled**/enabled) Remove 16-sprites-per-scanline hardware limit. - **Initial scanline** [pcfx_initial_scanline] ((0 to 40 in increments of 1. **4 is default**.) Adjust first display scanline. - **Last scanline** [pcfx_last_scanline] (208 to 238 in increments of 1. **235 is default**.) Adjust last display scanline. - **Mouse Sensitivity** [pcfx_mouse_sensitivity] (1.00 to 5.00 in increments of 0.25. **1.25 is default**.) Configure the sensitivity of the 'PCFX Mouse' device type, ## Controllers The Beetle PC-FX core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 - 2 device types - None - Doesn't disable input. - **PCFX Joypad** - Joypad - PCFX Mouse - Mouse ### Controller tables #### Joypad | User 1 - 6 Remap descriptors | RetroPad Inputs | |------------------------------|-------------------------------------------| | II | ![](../image/retropad/retro_b.png) | | IV | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Run | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | I | ![](../image/retropad/retro_a.png) | | III | ![](../image/retropad/retro_x.png) | | V | ![](../image/retropad/retro_l1.png) | | VI | ![](../image/retropad/retro_r1.png) | | MODE 1 (Switch) | ![](../image/retropad/retro_l2.png) | | MODE 2 (Switch) | ![](../image/retropad/retro_r2.png) | #### Mouse | RetroMouse Inputs | PCFX Mouse | |-----------------------------------------------------|-------------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | PCFX Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | PCFX Mouse Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | PCFX Mouse Right Button | ## Compatibility | Game | Issue | |-----------------------------------------------------------------|---------------------------------------------------------| | | | ## External Links - [Official Mednafen Website](https://mednafen.github.io/) - [Official Mednafen Downloads](https://mednafen.github.io/releases/) - [Libretro Beetle PC-FX Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mednafen_pcfx_libretro.info) - [Libretro Beetle PC-FX Github Repository](https://github.com/libretro/beetle-pcfx-libretro) - [Report Libretro Beetle PC-FX Core Issues Here](https://github.com/libretro/beetle-pcfx-libretro/issues) ================================================ FILE: docs/library/beetle_pce_fast.md ================================================ # NEC - PC Engine / CD (Beetle PCE FAST) ## Background Beetle/Mednafen PCE FAST is a libretro port of Mednafen PCE Fast with the PC Engine SuperGrafx module removed. The Beetle PCE FAST core has been authored by - [Mednafen Team](https://mednafen.github.io/) The Beetle PCE FAST core is licensed under - [GPLv2](https://github.com/libretro/beetle-pce-fast-libretro/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Required or optional firmware files go in RetroArch's system directory. !!! warning "" Which PCE CD BIOS file the Beetle PCE FAST core will use can be configured by the ['CD BIOS' core option](#core-options). !!! warning "" Any CD-ROM System BIOS will work, but some of them are known to be incompatible with certain games. | Filename | Description | md5sum | |:-------------:|:-------------------------------------:|:--------------------------------:| | syscard3.pce | Super CD-ROM2 System V3.xx - Required | 38179df8f4ac870017db21ebcbf53114 | | syscard2.pce | CD-ROM System V2.xx - Optional | | | syscard1.pce | CD-ROM System V1.xx - Optional | | | gexpress.pce | Game Express CD Card - Optional | | ## Extensions Content that can be loaded by the Beetle PCE FAST core have the following file extensions: - .pce - .cue - .ccd - .iso - .img - .bin - .chd RetroArch database(s) that are associated with the [Core name] core: - [NEC - PC Engine - TurboGrafx 16](https://github.com/libretro/libretro-database/blob/master/rdb/NEC%20-%20PC%20Engine%20-%20TurboGrafx%2016.rdb) - [NEC - PC Engine CD - TurboGrafx-CD](https://github.com/libretro/libretro-database/blob/master/rdb/NEC%20-%20PC%20Engine%20CD%20-%20TurboGrafx-CD.rdb) ## Features Frontend-level settings or features that the Beetle PCE FAST core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Directories The Beetle PCE FAST core's library name is 'Beetle PCE Fast' The Beetle PCE FAST core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:-----------:| | *.srm | Save | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ## Geometry and timing - The Beetle PCE FAST core's core provided FPS is 59.82 - The Beetle PCE FAST core's core provided sample rate is 44100 Hz - The Beetle PCE FAST core's base width is 512 - The Beetle PCE FAST core's base height is 243 - The Beetle PCE FAST core's max width is 512 - The Beetle PCE FAST core's max height is 243 - The Beetle PCE FAST core's core provided aspect ratio is 6/5 ## Loading PC Engine CD content To load PC Engine CD content, Beetle PCE FAST needs a cue-sheet that points to an image file. A cue sheet, or cue file, is a metadata file which describes how the tracks of a CD or DVD are laid out. If you have e.g. `foo.bin`, you should create a text file and save it as `foo.cue`. If you're playing a single-track Saturn game, then the cue file contents should look like this: `foobin.cue` ``` FILE "foo.bin" BINARY TRACK 01 MODE1/2352 INDEX 01 00:00:00 ``` After that, you can load the `foo.cue` file in RetroArch with the Beetle PCE FAST core. !!! warning "" Certain PC Engine content are multi-track, so their .cue files might be more complicated. ISO + OGG and ISO + WAV format games are supported, but they require a properly formatted cue sheet. For iso files, tracks should be denoted as BINARY, for ogg files, they should be denoted as OGG, and for wav files, they should be denoted as WAVE. ## CHD Alternatively to using cue sheets with .bin/.iso files, you can convert your games to .chd (MAME Compressed Hunks of Data) to reduce file sizes and neaten up your game folder. To convert content to CHD format, use the chdman tool found inside the latest MAME distribution and point it to a .cue file, like so: ``` chdman createcd --input foo.cue --output foo.chd ``` ## Core options The Beetle PCE FAST core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **CD Image Cache (Restart)** [pce_fast_cdimagecache] (**disabled**/enabled) Loads the complete image in memory at startup. Can potentially decrease loading times at the cost of increased startup time. - **CD Bios (Restart)** [pce_fast_cdbios] (**System Card 3**/Games Express/System Card 1/System Card 2) Select which PC Engine CD BIOS to use. - **No Sprite Limit (Restart)** [pce_nospritelimit] (**disabled**/enabled") Remove 16-sprites-per-scanline hardware limit. - **CPU Overclock Multiplier (Restart)** [pce_ocmultiplier] (**1**/2/3/4/5/6/7/8/9/10/20/30/40/50) Overclock the emulated CPU. - **Horizontal Overscan (352 Width Mode Only)** [pce_hoverscan] (300 to 352 in increments of 2. **352 in default**.) Modify the horizontal overscan. - **Initial scanline** [pce_initial_scanline] (0 to 40 in increments of 1. **3 is default.**) Adjust initial display scanline. - **Last scanline** [pce_last_scanline] (208 to 242 in increments of 1. **242 is default.**) Adjust last display scanline. - **(CD) CDDA Volume %** [pce_cddavolume] (0 to 200 in increments of 10. **100 is default**.) Adjust CDDA Volume %. - **(CD) ADPCM Volume %** [pce_adpcmvolume] (0 to 200 in increments of 10. **100 is default**.) Adjust ADPCM Volume %. - **(CD) CD PSG Volume %** [pce_cdpsgvolume] (0 to 200 in increments of 10. **100 is default**.) Adjust CD PSG Volume %. - **(CD) CD Speed** [pce_cdspeed] (**1**/2/4/8) Set the speed of the emulated CD drive. - **Turbo Delay** [pce_Turbo_Delay] (**Fast**/Medium/Slow) Adjust turbo delay. - **Turbo ON/OFF Toggle** [pce_Turbo_Toggling] (**disabled**/enabled) Enables Turbo ON/OFF inputs. Look at the [Joypad section](#joypad) for more information. - **Alternate Turbo Hotkey** [pce_turbo_toggle_hotkey] (**disabled**/enabled) Enables Alternate Turbo ON/OFF inputs. You can avoid remapping Button III and IV when switching to 6-button gamepad mode with this. Look at the [Joypad section](#joypad) for more information. - **P1 Turbo I** [pce_p0_turbo_I_enable] (**disabled**/enabled) Awaiting description. - **P1 Turbo II** [pce_p0_turbo_II_enable] (**disabled**/enabled) Awaiting description. - **P2 Turbo I** [pce_p1_turbo_I_enable] (**disabled**/enabled) Awaiting description. - **P2 Turbo II** [pce_p1_turbo_II_enable] (**disabled**/enabled) Awaiting description. - **P3 Turbo I** [pce_p2_turbo_I_enable] (**disabled**/enabled) Awaiting description. - **P3 Turbo II** [pce_p2_turbo_II_enable] (**disabled**/enabled) Awaiting description. - **P4 Turbo I** [pce_p3_turbo_I_enable] (**disabled**/enabled) Awaiting description. - **P4 Turbo II** [pce_p3_turbo_II_enable] (**disabled**/enabled) Awaiting description. - **P5 Turbo I** [pce_p4_turbo_I_enable] (**disabled**/enabled) Awaiting description. - **P5 Turbo II** [pce_p4_turbo_II_enable] (**disabled**/enabled) Awaiting description. ## User 1 - 2 device types The Beetle PCE FAST core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): - None - Doesn't disable input. - **PCE Joypad** - Joypad - Mouse - Mouse ## Joypad - Which PCE Joypad button mode is in use can be configured by the Mode Switch input. - The regular Turbo inputs for 2-button mode are only active when the ['Turbo ON/OFF Toggle' core option](#core-options) is set to On. - The Alternate Turbo inputs for 2-button mode are only active when the ['Turbo ON.mdOFF Toggle' core option](#core-options) is set to On and the ['Alternate Turbo Hotkey' core option](#core-options) is set to On. | RetroPad Inputs | User 1 - 5 input descriptors | PCE Joypad 2-button | PCE Joypad 6-button | |------------------------------------------------|------------------------------|---------------------------|---------------------| | ![](../image/retropad/retro_b.png) | II | II | II | | ![](../image/retropad/retro_y.png) | III | II Turbo On/Off | III | | ![](../image/retropad/retro_select.png) | Select | Select | Select | | ![](../image/retropad/retro_start.png) | Run | Run | Run | | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | D-Pad Up | D-Pad Up | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | D-Pad Down | D-Pad Down | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | D-Pad Left | D-Pad Left | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | D-Pad Right | D-Pad Right | | ![](../image/retropad/retro_a.png) | I | I | I | | ![](../image/retropad/retro_x.png) | IV | I Turbo On/Off | IV | | ![](../image/retropad/retro_l1.png) | V | | V | | ![](../image/retropad/retro_r1.png) | VI | | VI | | ![](../image/retropad/retro_l2.png) | Mode Switch | Mode Switch | Mode Switch | | ![](../image/retropad/retro_r2.png) | | Alternate II Turbo On/Off | | | ![](../image/retropad/retro_r3.png) | | Alternate I Turbo On/Off | | ## Mouse | RetroMouse Inputs | Mouse | |-------------------------------------------------------|--------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | Mouse Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | Mouse Right Button | ## External Links - [Official Mednafen Website](https://mednafen.github.io/) - [Official Mednafen Downloads](https://mednafen.github.io/releases/) - [Libretro Beetle PCE FAST Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mednafen_pce_fast_libretro.info) - [Libretro Beetle PCE FAST Github Repository](https://github.com/libretro/beetle-pce-fast-libretro) - [Report Libretro Beetle PCE FAST Core Issues Here](https://github.com/libretro/beetle-pce-fast-libretro/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0IcICSGZARi72aNezAyfpKzJ) ## TG-16 - [NEC - PC Engine SuperGrafx (Beetle SGX)](beetle_sgx.md) ================================================ FILE: docs/library/beetle_psx.md ================================================ # PlayStation (Beetle PSX) ## Background Beetle PSX is a port/fork of Mednafen's PSX module to the libretro API. It can be compiled in C++98 mode. Beetle PSX currently runs on Linux, OSX and Windows. Notable additions in this fork are: - PBP and CHD file format support, developed by Zapeth; - Software renderer internal resolution upscaling, implemented by simias; - PGXP subpixel precision, developed by iCatButler; Beetle PSX prioritizes accuracy and offers a software renderer that faithfully replicates the original PlayStation experience. However, it lacks hardware rendering capabilities. For those seeking improved visuals and performance, Beetle PSX HW provides a hardware-accelerated alternative. However, it's important to note that all games experience graphical glitches and rendering issues of varying severity with its OpenGL renderer ([example](https://github.com/libretro/beetle-psx-libretro/issues/900)). Fortunately, Beetle PSX HW offers a more stable alternative – the Vulkan renderer. This choice delivers hardware acceleration with accuracy closer to the software renderer, making it a compelling middle ground. The Beetle PSX core has been authored by - [Mednafen Team](https://mednafen.github.io/) The Beetle PSX core is licensed under - [GPLv2](https://github.com/libretro/beetle-psx-libretro/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Required or optional firmware files go in the frontend's `system` directory. | Filename | Description | md5sum | |:---------------:|:-------------------------------------:|:--------------------------------:| | scph5500.bin | PS1 JP BIOS - Required for JP games | 8dd7d5296a650fac7319bce665a6a53c | | scph5501.bin | PS1 US BIOS - Required for US games | 490f666e1afb15b7362b406ed1cea246 | | scph5502.bin | PS1 EU BIOS - Required for EU games | 32736f17079d0b2b7024407c39bd3050 | As a replacement for any of the BIOS files mentioned above, it is also possible to use either of these BIOSes: - `PSXONPSP660.bin` (MD5: c53ca5908936d412331790f4426c6c33) - `ps1_rom.bin` (MD5: 81bbe60ba7a3d1cea1d48c14cbcc647b) The `PSXONPSP660.bin` BIOS comes from the PSP, and the `ps1_rom.bin` BIOS comes from the PS3, both are region-free. For Beetle PSX to recognize either of these BIOSes, you need to enable the "Override BIOS" option. ## Extensions Content that can be loaded by the Beetle PSX core have the following file extensions: - .cue - .toc - .m3u - .ccd - .exe - .pbp - .chd RetroArch database(s) that are associated with the Beetle PSX core: - [Sony - PlayStation](https://github.com/libretro/libretro-database/blob/master/rdb/Sony%20-%20PlayStation.rdb) ## Features Frontend-level settings or features that the Beetle PSX core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✔ | | Rumble | ✔ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✔ | | Username | ✕ | | Language | ✕ | | Crop Overscan * | ✕ | | LEDs | ✕ | \* Overscan cropping available via Core Options instead of frontend settings ### Directories The Beetle PSX core's library name is 'Beetle PSX' The Beetle PSX core saves/loads to/from these directories. **Frontend's Save directory** - Memory cards **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ### Geometry and timing - The Beetle PSX core's core provided FPS is 59.826 for NTSC games and 49.761 for PAL games (non-interlaced rates) and is toggleable to 59.940 for NTSC games and 50.000 for PAL games (interlaced rates) through core options - The Beetle PSX core's core provided sample rate is 44100 Hz - The Beetle PSX core's base width is 320 - The Beetle PSX core's base height is 240 - The Beetle PSX core's max width is 700 when the 'Internal GPU resolution' is set to 1x. Raising the resolution past 1x will increase the max width - The Beetle PSX core's max height is 576 when the 'Internal GPU resolution' is set to 1x. Raising the resolution past 1x will increase the max height - The Beetle PSX core's core provided aspect ratio is automatically set based on core options ## Loading content Beetle PSX needs a cue-sheet that points to an image file. A cue sheet, or cue file, is a metadata file which describes how the tracks of a CD or DVD are laid out. If you have e.g. `foo.bin`, you should create a text file and save it as `foo.cue`. Most PS1 games are single-track, so the cue file contents should look like this: `foobin.cue` ``` FILE "foo.bin" BINARY TRACK 01 MODE1/2352 INDEX 01 00:00:00 ``` After that, you can load the `foo.cue` file in RetroArch with the Beetle PSX core. !!! attention Certain PS1 games are multi-track, so their .cue files might be more complicated. ### Playing PAL copy protected games PAL copy protected games need a SBI Subchannel file next to the bin/cue files in order to get past the copy protection. - Ape Escape (Europe).bin - Ape Escape (Europe).cue - **Ape Escape (Europe).sbi** !!! warning For proper PAL game compatibility, the 'Skip BIOS' core option needs to be set to off. ### Multiple-disk games If foo is a multiple-disk game, you should have .cue files for each one, e.g. `foo (Disc 1).cue`, `foo (Disc 2).cue`, `foo (Disc 3).cue`. To take advantage of Disc Control feature for disk swapping, an index file (a m3u file) should be made. Create a text file and save it as `foo.m3u`. Then enter your game's .cue files on it. The m3u file contents should look something like this: `foo.m3u` ``` foo (Disc 1).cue foo (Disc 2).cue foo (Disc 3).cue ``` After that, you can load the `foo.m3u` file in RetroArch with the Beetle PSX core. Here's a m3u example done with Valkryie Profile ![](../image/core/beetle_psx_hw/m3u.png) !!! attention Adding multi-track games to a RetroArch playlist is recommended. (Manually add an entry a playlist that points to `foo.m3u`) #### Swapping disks Disks can be swapped through Quick Menu -> Disc Control in RetroArch. If not using .m3u files, .cue files must be manually selected via the Load New Disk legacy feature. If using .m3u files, disks can be swapped by selecting Eject Disk, changing the Current Disk Index to your desired disk, and finally selecting Insert Disk. ### Compressed content Alternatively to using cue sheets with .bin/.iso files, you can convert your games to .pbp (Playstation Portable update file) or .chd (MAME Compressed Hunks of Data) to reduce file sizes and neaten up your game folder. #### PBP A recommended .pbp convert tool is PSX2PSP. If converting a multiple-disk game, all disks should be added to the same .pbp file, rather than making a .m3u file for them. Most conversion tools will want a single .bin file for each disk. If your game uses multiple .bin files (tracks) per disk, you will have to mount the cue sheet to a virtual drive and re-burn the images onto a single track before conversion. For multi-disk PAL copy-protected games, change the sbi file syntax from `[filename].sbi` to `[filename]_[disc_number].sbi` - Final Fantasy IX (Germany).pbp - **Final Fantasy IX (Germany)_1.sbi** - **Final Fantasy IX (Germany)_2.sbi** - **Final Fantasy IX (Germany)_3.sbi** - **Final Fantasy IX (Germany)_4.sbi** !!! attention RetroArch does not currently have .pbp database due to variability in users' conversion methods. All .pbp games will have to be added to playlists manually. #### CHD To convert content to CHD format, use the chdman tool found inside the latest MAME distribution and point it to a .cue file, like so: ``` chdman createcd --input foo.cue --output foo.chd ``` Note that the tool currently does not integrate .sbi files into the .chd, so these must be placed alongside the resulting .chd file in order to properly play games with LibCrypt protection. !!! attention For multi-disc content, make an .m3u file that lists all the .chd files instead of .cue files. Like the PBP files, content must be added to playlists manually. ## Saves For game savedata storage, the PSX console used memory cards. The PSX console had two slots for memory cards. In this doc, the first memory card slot will be referred to as 'Memcard slot 0' and the second slot will be referred to as 'Memcard slot 1'. For memory card functionality and usage, the Beetle PSX core will either use the Libretro savedata format or the Mednafen savedata format.
| Libretro savedata format | Mednafen savedata format | |----------------------------|----------------------------------| | gamename.srm | gamename.slot#.mcr |
**By default**, the Beetle PSX core will use Libretro's savedata format for Memcard slot 0 and Mednafen's savedata format for Memcard slot 1.
| Memcard slot 0 | Memcard slot 1 | |----------------|----------------| | gamename.srm | gamename.1.mcr |
!!! attention Memory card behavior can be controlled with the following [core options](#core-options) (Memcard 0 method, Enable memory card 1, Shared memcards). **By default**, the filenames of the Memcard savedata will match the loaded cue or m3u or pbp filename, like this: - Loaded content: Breath of Fire III (USA).cue - **Memcard slot 0: Breath of Fire III (USA).srm** - **Memcard slot 1: Breath of Fire III (USA).1.mcr** or - Loaded content: Final Fantasy VII (USA).m3u - **Memcard slot 0: Final Fantasy VII (USA).srm** - **Memcard slot 1: Final Fantasy VII (USA).1.mcr** or - Loaded content: Wild Arms 2 (USA).pbp - **Memcard slot 0: `Wild Arms 2 (USA).srm** - **Memcard slot 1: `Wild Arms 2 (USA).1.mcr** !!! attention To import your old memory cards from other emulators, you need to rename them to either the Libretro savedata format or the Mednafen savedata format. The Libretro (.srm) savedata format, when used with Beetle PSX, is internally identical to the Mednafen PSX (.mcr) savedata format, and can be converted between one another via renaming. !!! warning Keep in mind that save states also include the state of the memory card; carelessly loading an old save state will **OVEWRITE** the memory card, potentially resulting in lost saved games. **You can set the 'Don't overwrite SaveRAM on loading savestate' option in RetroArch's Saving settings to On to prevent this.** ## Core options The Beetle PSX core has the following options that can be tweaked from your frontend's core options menu or manually changed via core configuration files. Options are listed below in the following format: ``Option Name [option_key] (setting1/setting2/...)`` To manually change an option, search for that option's key in the core configuration file you want to edit and set it to your desired setting value, enclosed in quotations. For example, if you had set the Internal Color Depth to 32bpp and wanted to revert it to 16bpp, you would change ``beetle_psx_depth = "32bpp"`` to ``beetle_psx_depth = "16bpp(native)"``. Manually editing core configuration files is typically unnecessary unless your frontend does not have a method for toggling options. The default setting for each option will be highlighted in bold. Settings with (Restart) means that core has to be shut down for the new setting to be applied on next launch. - **Internal GPU Resolution** [beetle_psx_internal_resolution] (**1x(native)**/2x/4x/8x/16x) Selects internal resolution multiplier. Resolutions higher than 1x(native) improve the fidelity of 3D models at the expense of increased performance requirements. 2D elements are generally unaffected by this setting from the core's perspective. ??? note "*Internal GPU Resolution - 1x*" ![](../image/core/beetle_psx_hw/gpu_1.png) ??? note "*Internal GPU Resolution - 2x*" ![](../image/core/beetle_psx_hw/gpu_2.png) - **Dithering Pattern** [beetle_psx_dither_mode] (**1x(native)**/internal resolution/disabled) Select dithering pattern. Dithering is used by the original PSX hardware to combat the color banding visible due to 16bpp color depth. '1x(native)' emulates original hardware but can look grainy at higher internal resolutions. 'internal resolution' reduces graininess by allowing for finer dithering at higher Internal GPU Resolutions, but has limited effectiveness in combating color banding if the Internal GPU Resolution is set too high. (Note in the examples below that the 'internal resolution' option is less grainy but has more visible banding than '1x(native)' at 4x Internal GPU Resolution) 'disabled' is for users who otherwise wish to turn off dithering regardless of color banding. ??? note "*Dithering Pattern - 1x Native*" ![](../image/core/beetle_psx_hw/dither_native.png) ??? note "*Dithering Pattern - Internal Resolution*" ![](../image/core/beetle_psx_hw/dither_internalres.png) ??? note "*Dithering Pattern - Disabled*" ![](../image/core/beetle_psx_hw/dither_off.png) - **PGXP Operation Mode** [beetle_psx_pgxp_mode] (**disabled**/memory only/memory + CPU) Enabling the Parallel/Precision Geometry Transform Pipeline (PGXP) allows polygons to be rendered with subpixel precision, eliminating or otherwise diminishing the polygon jitter/wobble visible on original PSX hardware. This distortion results from original hardware using fixed point mathematics when rendering 3D models, thus rounding polygon vertices to the nearest integer pixel. 'disabled' emulates original hardware behavior. 'memory only' mode enables subpixel precision at the cost of increased performance requirements with only minor compatibility issues. 'memory + CPU' mode can further reduce jitter but is highly demanding and is known to cause geometry errors. 'memory only' is recommended for best compatibility. [https://www.youtube.com/watch?v=EYCpd_1lPUc](https://www.youtube.com/watch?v=EYCpd_1lPUc) - **Display Internal FPS** [beetle_psx_display_internal_fps] (**disabled**/enabled) Displays the frame rate that the emulated PSX is drawing at. Requires onscreen notifications to be enabled in the libretro frontend. Reported values may be inaccurate. ??? note "*Display internal FPS - On*" ![](../image/core/beetle_psx_hw/fps.png) - **Line-to-Quad Hack** [beetle_psx_line_render] (**default**/aggressive/disabled) Certain games employ a special technique for drawing horizontal lines, which involves stretching single-pixel-high triangles across the screen in a manner that causes the PSX hardware to rasterise them as a row of pixels. Examples include Doom/Hexen, and the water effects in Soul Blade. When running such games with an Internal GPU Resolution higher than native, these triangles no longer resolve as a line, causing gaps to appear in the output image. Setting 'Line-to-Quad Hack' to 'Default' solves this issue by detecting small triangles and converting them as required. The 'Aggressive' option will likely introduce visual glitches due to false positives, but is needed for correct rendering of some 'difficult' titles (e.g. Dark Forces, Duke Nukem). - **Frame Duping (Speedup)** [beetle_psx_frame_duping] (**disabled**/enabled) When enabled, provides a small performance increase by redrawing/reusing the last rendered frame (instead of presenting a new one) if the content of the current frame is unchanged based on the internal fps heuristic. May cause inaccurate behavior or lost animation frames, so it is not recommended to use this unless necessary. - **CPU Dynarec** [beetle_psx_cpu_dynarec] (**disabled**/execute/execute_once/run_interpreter) Dynamically recompile CPU instructions to native instructions. Much faster than interpreter, but CPU timing is less accurate, and may have bugs. - **Dynarec Code Invalidation** [beetle_psx_dynarec_invalidate] (**full**/dma) Some games require Full invalidation, some require DMA Only. This option has no effect when CPU Dynarec is not enabled. - **Dynarec DMA/GPU Event Cycles** [beetle_psx_dynarec_eventcycles] (**128**/256/384/512/640/768/896/1024) Max cycles run by CPU before a GPU or DMA Update is checked, higher number will be faster, has much less impact on beetle interpreter than dynarec. Leave at 128 for default Beetle interpreter behavior when CPU Dynarec is not enabled. - **CPU Frequency Scaling (Overclock)** [beetle_psx_cpu_freq_scale] (50% to 750% in increments of 10%. Default: **100%(native)**) Enable overclocking (or underclocking) of the emulated PSX's CPU. The default frequency of the MIPS R3000A-compatible 32-bit RISC CPU is 33.8688 MHz; running at higher frequencies can eliminate slowdown and improve frame rates in certain games at the expense of increased performance requirements. Note that some games have an internal frame rate limiter and may not benefit from overclocking. It is generally not recommended to adjust this setting as it causes many games or portions of them to run at unintended speeds. This can lead to audio and video desynchronization, among other issues. Leave at default for most games. - **GTE Overclock** [beetle_psx_gte_overclock] (**disabled**/enabled) When enabled, reduces the latency of operations involving the emulated PSX's Geometry Transform Engine (CPU coprocessor used for calculations related to 3D projection - i.e. all 3D graphics) to 1 cycle per instruction and additionally eliminates all memory access or cache fetch latency. For games that make heavy use of the GTE, this can greatly improve frame rate (and frame time) stability at the expense of increased performance requirements. Currently unstable -- leave off if unsure. - **GPU Rasterizer Overclock** [beetle_psx_gpu_overclock] (**1x(native)**/2x/4x/8x/16x/32x) Enables overclocking of the 2D rasterizer contained within the emulated PSX's GPU. Does not improve 3D rendering, and in general has little effect. - **Skip BIOS** [beetle_psx_skip_bios] (**disabled**/enabled) When enabled, skips the PSX BIOS animation normally displayed with starting content. **Enabling this option will cause compatibility issues with a small minority of games (Saga Frontier, PAL copy protected games, etc).** ??? note "*Skip BIOS - Off*" ![](../image/core/beetle_psx_hw/bios.png) - **Core-Reported FPS Timing** [beetle_psx_core_timing_fps] (**force_progressive**/force_interlaced/auto_toggle) Sets FPS timing that the core will report to the frontend. Automatic toggling will allow the core to switch between reporting progressive and interlaced rates, but may cause frontend video/audio driver reinits. Progressive timings are 59.826 for NTSC content and 49.761 for PAL content, and interlaced timings are 59.940 for NTSC content and 50.000 for PAL content. - **Core Aspect Ratio** [beetle_psx_aspect_ratio] (**corrected**/uncorrected/4:3) Set core provided aspect ratio. This setting is ignored when the Widescreen Mode Hack or Display Full VRAM options are enabled. "4:3" forces the core aspect ratio to 4:3 without taking horizontal overscan cropping or visible scanlines into account. The "4:3" setting should not be used and is only provided as a legacy feature for users desiring old incorrect behavior from the core. - **Widescreen Mode Hack** [beetle_psx_widescreen_hack] (**disabled**/enabled) Forces content to be rendered with an aspect ratio of 16:9. Produces best results with fully 3D games. Can cause graphical glitches or alignment/stretching issues in games that mix 3D and 2D elements. Leave off for most games. ??? note "*Widescreen mode hack - Off*" ![](../image/core/beetle_psx_hw/wide_off.png) ??? note "*Widescreen mode hack - On*" ![](../image/core/beetle_psx_hw/wide_on.png) - **Crop Horizontal Overscan** [beetle_psx_crop_overscan] (**enabled**/disabled) By default, Beetle PSX includes horizontal padding (black bars or 'pillarboxes' on either side of the screen) to emulate the same black bars generated in analog video output by real PSX hardware. This horizontal padding can contain garbage pixels that are generated when the game's width mode is smaller than the display area width in the emulated GPU registers. Enabling 'Crop Horizontal Overscan' will remove this potentially glitchy horizontal overscan region. Not all games will benefit from enabling this setting as shown in the examples below. ??? note "*Crop Overscan - Off (Game with Garbage Pixels)*" ![](../image/core/beetle_psx_hw/crop_off.png) ??? note "*Crop Overscan - On (Game with Garbage Pixels)*" ![](../image/core/beetle_psx_hw/crop_on.png) ??? note "*Crop Overscan - Off (Game with No Issues)*" ![](../image/core/beetle_psx_hw/scan_off.png) ??? note "*Crop Overscan - On (Game with No Issues)*" ![](../image/core/beetle_psx_hw/scan_on.png) This option does not affect vertical overscan. Vertical overscan can be cropped using the Initial/Last Scanline core options. - **Additional Cropping** [beetle_psx_image_crop] (**disabled**/1px/2px/3px/4px/5px/6px/7px/8px) When 'Crop Horizontal Overscan' is enabled, this option further reduces the width of the cropped image by the specified number of pixels. Note: This can have unintended consequences. While the absolute width is reduced, the resultant video is still scaled to the currently set aspect ratio. Enabling 'Additional Cropping' may therefore cause horizontal stretching. - **Offset Cropped Image** [beetle_psx_image_offset] (**disabled**/-4px/-3px/-2px/-1px/+1px/+2px/+3px/+4px) When 'Crop Horizontal Overscan' is enabled, allows the resultant cropped image to be offset horizontally to the right (positive) or left (negative) by the specified number of pixels. May be used to correct alignment issues. - **Initial Scanline - NTSC** [beetle_psx_initial_scanline] (0 to 40 in increments of 1. Default: **0**) Selects the first displayed scanline when running NTSC content. Setting a value greater than 0 will reduce the height of output images by cropping pixels from the topmost edge. May be used to counteract letterboxing built in to some games. - **Last Scanline - NTSC** [beetle_psx_last_scanline] (210 to 239 in increments of 1. Default: **239**) Selects the last displayed scanline when running NTSC content. Setting a value less than 239 will reduce the height of output images by cropping pixels from the bottommost edge. May be used to counteract letterboxing built in to some games. - **Initial Scanline - PAL** [beetle_psx_initial_scanline_pal] (0 to 40 in increments of 1. Default: **0**) Selects the first displayed scanline when running PAL content. Setting a value greater than 0 will reduce the height of output images by cropping pixels from the topmost edge. May be used to counteract letterboxing built in to some games. - **Last Scanline - PAL** [beetle_psx_last_scanline_pal] (230 to 287 in increments of 1. Default: **287**) Selects the last displayed scanline when running PAL content. Setting a value less than 287 will reduce the height of output images by cropping pixels from the bottommost edge. May be used to counteract letterboxing built in to some games. - **CD Access Method (Restart)** [beetle_psx_cd_access_method] (**sync**/async/precache) Selects method used to read data from content disc images. 'sync' emulates original hardware. 'async' can alleviate stuttering on devices with slow storage. 'precache' loads the entire disc image into memory when starting content, incurring a small startup delay. This can improve in-game loading times and eliminate stutters due to emulated CD access, but may cause issues on systems with low memory. - **CD Loading Speed** [beetle_psx_cd_fastload] (**2x(native)**/4x/6x/8x/10x/12x/14x) Selects disk access speed multiplier. This speedhack can greatly reduce loading times at speeds higher than native but is known to introduce texture corruption errors, timing glitches, or loading screen softlocks in many titles. Some games will not work at all if loading speed is not set to native (e.g. Castlevania: Symphony of the Night). **Reduce multiplier value if experiencing loading issues, freezes, etc.** - **Memory Card 0 Method (Restart)** [beetle_psx_use_mednafen_memcard0_method] (**libretro**/mednafen) Choose the savedata format used for Memory Card 0. See the [Saves section](#saves) above for an explanation regarding the libretro and mednafen formats. libretro is recommended, but mednafen may be used for compatibility with the standalone version of Mednafen. The libretro (.srm) and Mednafen (.mcr) formats are internally identical when used with Beetle PSX. Note: This option must be set to 'mednafen' if the Shared Memcards option is enabled. - **Enable Memory Card 1 (Restart)** [beetle_psx_enable_memcard1] (**enabled**/disabled) Selects whether to emulate a second memory card in Slot 1. When disabled, games can only access the memory card in Slot 0. Note: Some games require this option to be disabled for correct operation (e.g. Codename Tenka). - **Shared Memory Cards (Restart)** [beetle_psx_shared_memory_cards] (**disabled**/enabled) When enabled, games will save and load using the same memory card files. Note: The "Memcard 0 Method" option must be set to 'mednafen' for this option to function properly. When disabled, separate memory card files will be generated for each title. This option is useful for games in series such as Suikoden or Arc the Lad that check for save data from previous titles.
| Memcard slot 0 | Memcard slot 1 | |------------------------------------|------------------------------------| | mednafen_psx_libretro_shared.0.mcr | mednafen_psx_libretro_shared.1.mcr |
- **Analog Self-Calibration** [beetle_psx_analog_calibration] (**disabled**/enabled) When enabled, monitors the max values reached by the input, using it as a calibration heuristic which then scales the analog coordinates sent to the emulator accordingly. For best results, rotate the sticks at max amplitude for the algorithm to get a good estimate of the scaling factor, otherwise it will adjust while playing. While modern analog sticks have circular logical ranges, older analog sticks such as those on the DualShock have logical ranges closer to squares and can report larger values at the intercardinal directions than modern analog sticks can. Games that expect these larger values will have issues controlling with modern analog sticks, which this option can solve by scaling modern analog stick values up. - **Enable DualShock Analog Mode Toggle** [beetle_psx_analog_toggle] (**disabled**/enabled) When the input device type is set to DualShock, this option determines whether or not the Analog Button on that device can be toggled. When this option is disabled, the DualShock input device will be locked in Analog Mode where the analog sticks are on. When this option is enabled, the DualShock input device can be toggled between Digital Mode (analog sticks off) and Analog Mode (analog sticks on) much like real hardware by pressing and holding START+SELECT+L1+L2+R1+R2 for one second in lieu of a dedicated Analog Button. Note: Some games may not respond to input when the DualShock is in Analog Mode. Either enable Analog Button Toggle and toggle the DualShock to Digital Mode or change your input device type to PlayStation Controller. - **Port 1: Multitap Enable** [beetle_psx_enable_multitap_port1] (**disabled**/enabled) Enables/Disables multitap functionality on port 1. - **Port 2: Multitap Enable** [beetle_psx_enable_multitap_port2] (**disabled**/enabled) Enables/Disables multitap functionality on port 2. - **Gun Input Mode** [beetle_psx_gun_input_mode] (**lightgun**/touchscreen) When device type is set to 'Guncon / G-Con 45' or 'Justifier', specify whether to use a mouse-controlled 'Light Gun' or 'Touchscreen' input. - **Gun Cursor** [beetle_psx_gun_cursor] (**cross**/dot/off) Selects the gun cursor to be displayed on screen while using the the 'Guncon / G-Con 45' and 'Justifier' input device types. When disabled, cross hairs are always hidden. ??? note "*Gun Cursor - Cross*" ![](../image/core/beetle_psx_hw/cursor_cross.png) ??? note "*Gun Cursor - Dot*" ![](../image/core/beetle_psx_hw/cursor_dot.png) ??? note "*Gun Cursor - Off*" ![](../image/core/beetle_psx_hw/cursor_off.png) - **Mouse Sensitivity** [beetle_psx_mouse_sensitivity] (5% to 200% in increments of 5%. Default: **100%**) Configure the response of the 'Mouse' input device type. - **NegCon Twist Response** [beetle_psx_negcon_response] (**linear**/quadratic/cubic) Specifies the analog response when using a RetroPad left analog stick to simulate the 'twist' action of emulated [neGcon Controllers](https://en.wikipedia.org/wiki/NeGcon). 'linear': Analog stick displacement is mapped linearly to negCon rotation angle. 'quadratic': Analog stick displacement is mapped quadratically to negCon rotation angle. This allows for greater precision when making small movements with the analog stick. 'cubic': Analog stick displacement is mapped cubically to negCon rotation angle. This allows for even greater precision when making small movements with the analog stick, but 'exaggerates' larger movements. !!! attention A linear response is not recommended when using standard gamepad devices. The negCon 'twist' mechanism is substantially different from conventional analog sticks; linear mapping over-amplifies small displacements of the stick, impairing fine control. A linear response is only appropriate when using racing wheel peripherals. In most cases, the 'quadratic' option should be selected. This provides effective compensation for the physical differences between real/emulated hardware and is the closest approximation of real hardware, enabling smooth/precise analog input. - **NegCon Twist Deadzone** [beetle_psx_negcon_deadzone] (**0%**/5%/10%/15%/20%/25%/30%) Sets the deadzone of the RetroPad left analog stick when simulating the 'twist' action of emulated [neGcon Controllers](https://en.wikipedia.org/wiki/NeGcon). Used to eliminate drift/unwanted input. !!! attention Most (all?) negCon compatible titles provide in-game options for setting a 'twist' deadzone value. To avoid loss of precision, the in-game deadzone should *always* be set to zero. Any analog stick drift should instead be accounted for by configuring the 'NegCon Twist Deadzone' core option. This is particularly important when 'NegCon Twist Response' is set to 'quadratic' or 'cubic'. Xbox gamepads typically require a deadzone of 15-20%. Many Android-compatible bluetooth gamepads have an internal 'hardware' deadzone, allowing the deadzone value here to be set to 0%. For convenience, it is recommended to make use of the 'Options → Analog Setting 1P' menu of [Gran Turismo](https://en.wikipedia.org/wiki/Gran_Turismo_(video_game)) when calibrating the 'NegCon Twist Deadzone'. This provides a clear and precise representation of 'real' controller input values. ## User 1 - 8 device types The Beetle PSX core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): - None - Input disabled. - [**PlayStation Controller**](https://en.wikipedia.org/wiki/PlayStation_Controller) - Joypad - PlayStation Controller (SCPH-1080) - [DualShock](https://en.wikipedia.org/wiki/DualShock) - Joypad - DualShock (SCPH-1200) - [Analog Controller](https://en.wikipedia.org/wiki/Dual_Analog_Controller) - Joypad - PlayStation Dual Analog Controller(SCPH-1180) - [Analog Joystick](https://en.wikipedia.org/wiki/PlayStation_Analog_Joystick) - Joypad - PlayStation Analog Joystick (SCPH-1110) - [Guncon / G-Con 45](https://en.wikipedia.org/wiki/GunCon) - Lightgun - Namco Gun Controller (SLEH-00007) - [Justifier](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - Konami Justifier lightgun peripheral (SLEH-00005, SLUH-00017) - [Mouse](https://en.wikipedia.org/wiki/PlayStation_Mouse) - Mouse - PlayStation Mouse (SCPH-1090, SCPH-1030) - [neGcon](https://en.wikipedia.org/wiki/NeGcon) - Joypad - Namco third party controller ## Rumble support Rumble only works in the Beetle PSX core when - The content being ran has rumble support. - The frontend being used has rumble support. - The joypad device being used has rumble support. - The corresponding user's device type is set to **DualShock** ## Multitap support Activating multitap support in compatible games can be configured by the ['Port 1: Multitap enable' and 'Port 2: Multitap enable' core options](#core-options). ## Joypad ![](../image/controller/psx.png) | User 1 - 8 input descriptors | RetroPad Inputs | PlayStation Controller Inputs | DualShock Inputs | Analog Controller Inputs | Analog Joystick Inputs | neGcon Inputs | |-------------------------------|----------------------------------------------|------------------------------------------------|-------------------------------------------------|-------------------------------------------------|------------------------------------------------|---------------------------------| | Cross | ![](../image/retropad/retro_b.png) | ![](../image/Button_Pack/PS3/PS3_Cross.png) | ![](../image/Button_Pack/PS3/PS3_Cross.png) | ![](../image/Button_Pack/PS3/PS3_Cross.png) | ![](../image/Button_Pack/PS3/PS3_Cross.png) | Analog button I | | Square | ![](../image/retropad/retro_y.png) | ![](../image/Button_Pack/PS3/PS3_Square.png) | ![](../image/Button_Pack/PS3/PS3_Square.png) | ![](../image/Button_Pack/PS3/PS3_Square.png) | ![](../image/Button_Pack/PS3/PS3_Square.png) | Analog button II | | Select | ![](../image/retropad/retro_select.png) | ![](../image/Button_Pack/PS3/PS3_Select.png) | ![](../image/Button_Pack/PS3/PS3_Select.png) | ![](../image/Button_Pack/PS3/PS3_Select.png) | ![](../image/Button_Pack/PS3/PS3_Select.png) | | | Start | ![](../image/retropad/retro_start.png) | ![](../image/Button_Pack/PS3/PS3_Start.png) | ![](../image/Button_Pack/PS3/PS3_Start.png) | ![](../image/Button_Pack/PS3/PS3_Start.png) | ![](../image/Button_Pack/PS3/PS3_Start.png) | Start | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Up.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Up.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Up.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Up.png) | D-Pad Up | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Down.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Down.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Down.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Down.png) | D-Pad Down | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Left.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Left.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Left.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Left.png) | D-Pad Left | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Right.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Right.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Right.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Right.png) | D-Pad Right | | Circle | ![](../image/retropad/retro_a.png) | ![](../image/Button_Pack/PS3/PS3_Circle.png) | ![](../image/Button_Pack/PS3/PS3_Circle.png) | ![](../image/Button_Pack/PS3/PS3_Circle.png) | ![](../image/Button_Pack/PS3/PS3_Circle.png) | A | | Triangle | ![](../image/retropad/retro_x.png) | ![](../image/Button_Pack/PS3/PS3_Triangle.png) | ![](../image/Button_Pack/PS3/PS3_Triangle.png) | ![](../image/Button_Pack/PS3/PS3_Triangle.png) | ![](../image/Button_Pack/PS3/PS3_Triangle.png) | B | | L1 | ![](../image/retropad/retro_l1.png) | ![](../image/Button_Pack/PS3/PS3_L1.png) | ![](../image/Button_Pack/PS3/PS3_L1.png) | ![](../image/Button_Pack/PS3/PS3_L1.png) | ![](../image/Button_Pack/PS3/PS3_L1.png) | Left shoulder button (analog) | | R1 | ![](../image/retropad/retro_r1.png) | ![](../image/Button_Pack/PS3/PS3_R1.png) | ![](../image/Button_Pack/PS3/PS3_R1.png) | ![](../image/Button_Pack/PS3/PS3_R1.png) | ![](../image/Button_Pack/PS3/PS3_R1.png) | Right shoulder button (digital) | | L2 | ![](../image/retropad/retro_l2.png) | ![](../image/Button_Pack/PS3/PS3_L2.png) | ![](../image/Button_Pack/PS3/PS3_L2.png) | ![](../image/Button_Pack/PS3/PS3_L2.png) | ![](../image/Button_Pack/PS3/PS3_L2.png) | Analog button II | | R2 | ![](../image/retropad/retro_r2.png) | ![](../image/Button_Pack/PS3/PS3_R2.png) | ![](../image/Button_Pack/PS3/PS3_R2.png) | ![](../image/Button_Pack/PS3/PS3_R2.png) | ![](../image/Button_Pack/PS3/PS3_R2.png) | Analog button I | | L3 | ![](../image/retropad/retro_l3.png) | | ![](../image/Button_Pack/PS3/PS3_L3.png) | | | | | R3 | ![](../image/retropad/retro_r3.png) | | ![](../image/Button_Pack/PS3/PS3_R3.png) | | | | | Left Analog X | ![](../image/retropad/retro_left_stick.png) X | | ![](../image/Button_Pack/PS3/PS3_Left_Stick.png) | ![](../image/Button_Pack/PS3/PS3_Left_Stick.png) | Left Joystick X | Twist | | Left Analog Y | ![](../image/retropad/retro_left_stick.png) Y | | ![](../image/Button_Pack/PS3/PS3_Left_Stick.png) | ![](../image/Button_Pack/PS3/PS3_Left_Stick.png) | Left Joystick Y | | | Right Analog X | ![](../image/retropad/retro_right_stick.png) X | | ![](../image/Button_Pack/PS3/PS3_Right_Stick.png) | ![](../image/Button_Pack/PS3/PS3_Right_Stick.png) | Right Joystick X | | | Right Analog Y | ![](../image/retropad/retro_right_stick.png) Y | | ![](../image/Button_Pack/PS3/PS3_Right_Stick.png) | ![](../image/Button_Pack/PS3/PS3_Right_Stick.png) | Right Joystick Y | | ## Mouse | RetroMouse Inputs | Mouse Inputs | |-----------------------------------------------------|--------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | Mouse Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | Mouse Right Button | ## Lightgun | RetroLightgun Inputs | Guncon / G-Con 45 Inputs | Justifier Inputs | |------------------------------------------------------|-----------------------------|---------------------| | ![](../image/retromouse/retro_mouse.png) Gun Crosshair | Guncon / G-Con 45 Crosshair | Justifier Crosshair | | Gun Trigger | Guncon / G-Con 45 Trigger | Justifier Trigger | | Gun Reload | Guncon / G-Con 45 Reload | Justifier Reload | | Gun Aux A | Guncon / G-Con 45 A | Justifier Aux | | Gun Aux B | Guncon / G-Con 45 B | | | Gun Start | | Justifier Start | ## Compatibility A list of known emulation bugs can be found here [https://forum.fobby.net/index.php?t=msg&th=1114&start=0&](https://forum.fobby.net/index.php?t=msg&th=1114&start=0&) ## External Links - [Official Mednafen Website](https://mednafen.github.io/) - [Official Mednafen Downloads](https://mednafen.github.io/releases/) - [Beetle PSX Libretro Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mednafen_psx_libretro.info) - [Beetle PSX Libretro Github Repository](https://github.com/libretro/beetle-psx-libretro) - [Report Beetle PSX Core Issues Here](https://github.com/libretro/beetle-psx-libretro/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0IeQOnw9bnjwthht0iUvs2wk) ## Libretro PSX cores - [PlayStation (Beetle PSX HW)](beetle_psx_hw.md) - [PlayStation (PCSX ReARMed)](pcsx_rearmed.md) ================================================ FILE: docs/library/beetle_psx_hw.md ================================================ # PlayStation (Beetle PSX HW) ## Background Beetle PSX HW is a port/fork of Mednafen's PSX module to the libretro API. It can be compiled in C++98 mode, excluding the Vulkan renderer, which is written in C++11 for the time being. Beetle PSX HW currently runs on Linux, OSX and Windows. Notable additions in this fork are: - PBP and CHD file format support, developed by Zapeth; - Software renderer internal resolution upscaling, implemented by simias; - An OpenGL 3.3 renderer, developed by simias; - A Vulkan renderer, developed by TinyTiger; - PGXP perspective correct texturing and subpixel precision, developed by iCatButler; The Beetle PSX HW core has been authored by - [Mednafen Team](https://mednafen.github.io/) The Beetle PSX HW core is licensed under - [GPLv2](https://github.com/libretro/beetle-psx-libretro/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ### Requirements - OpenGL 3.3 for the opengl renderer - Vulkan for the vulkan renderer ## BIOS Required or optional firmware files go in the frontend's `system` directory. | Filename | Description | md5sum | |:---------------:|:-------------------------------------:|:--------------------------------:| | scph5500.bin | PS1 JP BIOS - Required for JP games | 8dd7d5296a650fac7319bce665a6a53c | | scph5501.bin | PS1 US BIOS - Required for US games | 490f666e1afb15b7362b406ed1cea246 | | scph5502.bin | PS1 EU BIOS - Required for EU games | 32736f17079d0b2b7024407c39bd3050 | As a replacement for any of the BIOS files mentioned above, it is also possible to use either of these BIOSes: - `PSXONPSP660.bin` (MD5: c53ca5908936d412331790f4426c6c33) - `ps1_rom.bin` (MD5: 81bbe60ba7a3d1cea1d48c14cbcc647b) The `PSXONPSP660.bin` BIOS comes from the PSP, and the `ps1_rom.bin` BIOS comes from the PS3, both are region-free. For Beetle PSX HW to recognize either of these BIOSes, you need to enable the "Override BIOS" option. ## Extensions Content that can be loaded by the Beetle PSX HW core have the following file extensions: - .cue - .toc - .m3u - .ccd - .exe - .pbp - .chd RetroArch database(s) that are associated with the Beetle PSX HW core: - [Sony - PlayStation](https://github.com/libretro/libretro-database/blob/master/rdb/Sony%20-%20PlayStation.rdb) ## Features Frontend-level settings or features that the Beetle PSX HW core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✔ | | Rumble | ✔ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✔ | | Username | ✕ | | Language | ✕ | | Crop Overscan * | ✕ | | LEDs | ✕ | \* Overscan cropping available via Core Options instead of frontend settings ### Directories The Beetle PSX HW core's library name is 'Beetle PSX HW' The Beetle PSX HW core saves/loads to/from these directories. **Frontend's Save directory** - Memory cards **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ### Geometry and timing - The Beetle PSX HW core's core provided FPS is 59.826 for NTSC games and 49.761 for PAL games (non-interlaced rates) and is toggleable to 59.940 for NTSC games and 50.000 for PAL games (interlaced rates) through core options - The Beetle PSX HW core's core provided sample rate is 44100 Hz - The Beetle PSX HW core's base width is 320 - The Beetle PSX HW core's base height is 240 - The Beetle PSX HW core's max width is 700 when the 'Internal GPU resolution' is set to 1x. Raising the resolution past 1x will increase the max width - The Beetle PSX HW core's max height is 576 when the 'Internal GPU resolution' is set to 1x. Raising the resolution past 1x will increase the max height - The Beetle PSX HW core's core provided aspect ratio is automatically set based on core options ## Loading content Beetle PSX HW needs a cue-sheet that points to an image file. A cue sheet, or cue file, is a metadata file which describes how the tracks of a CD or DVD are laid out. If you have e.g. `foo.bin`, you should create a text file and save it as `foo.cue`. Most PS1 games are single-track, so the cue file contents should look like this: `foobin.cue` ``` FILE "foo.bin" BINARY TRACK 01 MODE1/2352 INDEX 01 00:00:00 ``` After that, you can load the `foo.cue` file in RetroArch with the Beetle PSX HW core. !!! attention Certain PS1 games are multi-track, so their .cue files might be more complicated. ### Playing PAL copy protected games PAL copy protected games need a SBI Subchannel file next to the bin/cue files in order to get past the copy protection. - Ape Escape (Europe).bin - Ape Escape (Europe).cue - **Ape Escape (Europe).sbi** !!! warning For proper PAL game compatibility, the 'Skip BIOS' core option needs to be set to off. ### Multiple-disk games If foo is a multiple-disk game, you should have .cue files for each one, e.g. `foo (Disc 1).cue`, `foo (Disc 2).cue`, `foo (Disc 3).cue`. To take advantage of Disc Control feature for disk swapping, an index file (a m3u file) should be made. Create a text file and save it as `foo.m3u`. Then enter your game's .cue files on it. The m3u file contents should look something like this: `foo.m3u` ``` foo (Disc 1).cue foo (Disc 2).cue foo (Disc 3).cue ``` After that, you can load the `foo.m3u` file in RetroArch with the Beetle PSX HW core. Here's a m3u example done with Valkryie Profile ![](../image/core/beetle_psx_hw/m3u.png) !!! attention Adding multi-track games to a RetroArch playlist is recommended. (Manually add an entry a playlist that points to `foo.m3u`) #### Swapping disks Disks can be swapped through Quick Menu -> Disc Control in RetroArch. If not using .m3u files, .cue files must be manually selected via the Load New Disk legacy feature. If using .m3u files, disks can be swapped by selecting Eject Disk, changing the Current Disk Index to your desired disk, and finally selecting Insert Disk. ### Compressed content Alternatively to using cue sheets with .bin/.iso files, you can convert your games to .pbp (Playstation Portable update file) or .chd (MAME Compressed Hunks of Data) to reduce file sizes and neaten up your game folder. #### PBP A recommended .pbp convert tool is PSX2PSP. If converting a multiple-disk game, all disks should be added to the same .pbp file, rather than making a .m3u file for them. Most conversion tools will want a single .bin file for each disk. If your game uses multiple .bin files (tracks) per disk, you will have to mount the cue sheet to a virtual drive and re-burn the images onto a single track before conversion. For multi-disk PAL copy-protected games, change the sbi file syntax from `[filename].sbi` to `[filename]_[disc_number].sbi` - Final Fantasy IX (Germany).pbp - **Final Fantasy IX (Germany)_1.sbi** - **Final Fantasy IX (Germany)_2.sbi** - **Final Fantasy IX (Germany)_3.sbi** - **Final Fantasy IX (Germany)_4.sbi** !!! attention RetroArch does not currently have .pbp database due to variability in users' conversion methods. All .pbp games will have to be added to playlists manually. #### CHD To convert content to CHD format, use the chdman tool found inside the latest MAME distribution and point it to a .cue file, like so: ``` chdman createcd --input foo.cue --output foo.chd ``` Note that the tool currrently does not integrate .sbi files into the .chd, so these must be placed alongside the resulting .chd file in order to properly play games with LibCrypt protection. !!! attention For multi-disc content, make an .m3u file that lists all the .chd files instead of .cue files. Like the PBP files, content must be added to playlists manually. ## Texture replacements (Vulkan only) To use a textures pack you'll have to extract the textures in a `[game_filename]-texture-replacements/` folder inside your game directory, where "[game_filename]" matches the actual filename of the file you're using to load the game. Here's an example with Suikoden II: ``` Suikoden II (USA).bin Suikoden II (USA).cue Suikoden II (USA)-texture-replacements/ ``` Another example with Chrono Cross, a multi-discs game: ``` Chrono Cross (USA) (Disc 1).bin Chrono Cross (USA) (Disc 1).cue Chrono Cross (USA) (Disc 2).bin Chrono Cross (USA) (Disc 2).cue Chrono Cross (USA).m3u Chrono Cross (USA)-texture-replacements/ ``` For multi-discs games you will be loading the game with the .m3u (if you followed the ['Multiple-disk games'](#multiple-disk-games) section properly) so the textures folder name has to match the .m3u filename. !!! Tips If you still can't see any difference with your folder set up properly: - The .png files need to be inside `[game_filename]-texture-replacements/` directly, not in another subfolder and not inside a .zip file! - Both `Track Textures` and `Replace Textures` core options have to be enabled. - `Internal GPU Resolution` core option should be set to anything higher than '1x (Native)' and `Supersampling (Downsample to Native Resolution)` core option should be disabled, or you probably won't notice any difference at such low resolution. - Custom textures may not be applied directly when loading a save state, in this case you may have to trigger a scene change ingame (leaving or entering a new room for example) to force the textures to "refresh". ## Saves For game savedata storage, the PSX console used memory cards. The PSX console had two slots for memory cards. In this doc, the first memory card slot will be referred to as 'Memcard slot 0' and the second slot will be referred to as 'Memcard slot 1'. For memory card functionality and usage, the Beetle PSX HW core will either use the Libretro savedata format or the Mednafen savedata format.
| Libretro savedata format | Mednafen savedata format | |----------------------------|----------------------------------| | gamename.srm | gamename.slot#.mcr |
**By default**, the Beetle PSX HW core will use Libretro's savedata format for Memcard slot 0 and Mednafen's savedata format for Memcard slot 1.
| Memcard slot 0 | Memcard slot 1 | |----------------|----------------| | gamename.srm | gamename.1.mcr |
!!! attention Memory card behavior can be controlled with the following [core options](#core-options) (Memcard 0 method, Enable memory card 1, Shared memcards). **By default**, the filenames of the Memcard savedata will match the loaded cue or m3u or pbp filename, like this: - Loaded content: Breath of Fire III (USA).cue - **Memcard slot 0: Breath of Fire III (USA).srm** - **Memcard slot 1: Breath of Fire III (USA).1.mcr** or - Loaded content: Final Fantasy VII (USA).m3u - **Memcard slot 0: Final Fantasy VII (USA).srm** - **Memcard slot 1: Final Fantasy VII (USA).1.mcr** or - Loaded content: Wild Arms 2 (USA).pbp - **Memcard slot 0: `Wild Arms 2 (USA).srm** - **Memcard slot 1: `Wild Arms 2 (USA).1.mcr** !!! attention To import your old memory cards from other emulators, you need to rename them to either the Libretro (.srm) savedata format or the Mednafen (.mcr) savedata format. The Libretro (.srm) savedata format, when used with Beetle PSX, is internally identical to the Mednafen PSX (.mcr) savedata format, and can be converted between one another via renaming. !!! warning Keep in mind that save states also include the state of the memory card; carelessly loading an old save state will **OVEWRITE** the memory card, potentially resulting in lost saved games. **You can set the 'Don't overwrite SaveRAM on loading savestate' option in RetroArch's Saving settings to On to prevent this.** ## Core options The Beetle PSX HW core has the following options that can be tweaked from your frontend's core options menu or manually changed via core configuration files. Options are listed below in the following format: ``Option Name [option_key] (setting1/setting2/...)`` To manually change an option, search for that option's key in the core configuration file you want to edit and set it to your desired setting value, enclosed in quotations. For example, if you had set the Internal Color Depth to 32bpp and wanted to revert it to 16bpp, you would change ``beetle_psx_hw_depth = "32bpp"`` to ``beetle_psx_hw_depth = "16bpp(native)"``. Manually editing core configuration files is typically unnecessary unless your frontend does not have a method for toggling options. The default setting for each option will be highlighted in bold. Settings with (Restart) means that core has to be shut down for the new setting to be applied on next launch. - **Renderer (Restart)** [beetle_psx_hw_renderer] (**hardware**/hardware_gl/hardware_vk/software) Chooses which video renderer will be used. Software is the most accurate but generally has higher performance requirements when running at internal GPU resolutions higher than 1x. The software renderer also lacks certain enhancements exclusive to the hardware renderer. Hardware is less accurate but may have improved performance over the software renderer at internal GPU resolutions of 2x and above on capable hardware. The hardware renderers also allow various graphical enhancements such as higher color depth, texture filtering, and PGXP. Choosing **hardware** will automatically select either the Vulkan or OpenGL renderer depending on the current libretro frontend video driver. If the provided frontend video driver is not Vulkan or OpenGL (3.3 or higher) then the core will fall back to the software renderer at 1x internal resolution. **hardware_gl** and **hardware_vk** allow the core to ignore the frontend preferred hardware context and attempt to force a specific hardware renderer. If the core is unable to do so, it will fall back to the software renderer at 1x internal resolution. The ability to force specific renderers may not be available on all platforms. The hardware renderers have known issues -- check the compatibility section below or the core's [issue tracker](https://github.com/libretro/beetle-psx-libretro/issues) for more details. - **Software Framebuffer** [beetle_psx_hw_renderer_software_fb] (**enabled**/disabled) OpenGL/Vulkan Only Allows accurate emulation of framebuffer readback effects (e.g. motion blur, FF7 battle swirl, etc.) when using the hardware renderer. If disabled, certain operations are omitted or rendered on the GPU, which can improve performance but may cause graphical errors or [cause stuttering](https://github.com/libretro/beetle-psx-libretro/pull/469#issue-238935899). Leave enabled if unsure. - **Internal GPU Resolution** [beetle_psx_hw_internal_resolution] (**1x(native)**/2x/4x/8x/16x) Selects internal resolution multiplier. Resolutions higher than 1x(native) improve the fidelity of 3D models at the expense of increased performance requirements. 2D elements are generally unaffected by this setting from the core's perspective. ??? note "*Internal GPU Resolution - 1x*" ![](../image/core/beetle_psx_hw/gpu_1.png) ??? note "*Internal GPU Resolution - 2x*" ![](../image/core/beetle_psx_hw/gpu_2.png) - **Internal Color Depth** [beetle_psx_hw_depth] (**16bpp(native)**/32bpp) OpenGL Only The PSX has a limited color depth of 16 bits per pixel (bpp). This leads to banding effects (uneven color gradients) which are smoothed out by original hardware through the use of a dithering pattern. The '16bpp(native)' setting emulates the original 16bpp color depth. Selecting '32 bpp' increases the color depth such that smoother gradients can be achieved without dithering, allowing for a cleaner undithered output. Note the visible horizontal bands on an undithered 16bpp image compared to the same undithered image at 32bpp: ??? note "*Undithered 16bpp*" ![](../image/core/beetle_psx_hw/16bpp_no-dither.png) ??? note "*Undithered 32bpp*" ![](../image/core/beetle_psx_hw/32bpp_no-dither.png) This option should be toggled in conjunction with the Dithering Pattern option. The software renderer is locked to 16bpp while the Vulkan renderer will automatically set render at 16bpp if dithering is enabled and 32bpp if dithering is disabled. - **Dithering Pattern** [beetle_psx_hw_dither_mode] (**1x(native)**/internal resolution/disabled) Select dithering pattern. Dithering is used by the original PSX hardware to combat the color banding visible due to 16bpp color depth. This option is less necessary and can be disabled if the Internal Color Depth option is set to '32bpp'. '1x(native)' emulates original hardware but can look grainy at higher internal resolutions. 'internal resolution' reduces graininess by allowing for finer dithering at higher Internal GPU Resolutions, but has limited effectiveness in combating color banding if the Internal GPU Resolution is set too high. (Note in the examples below that the 'internal resolution' option is less grainy but has more visible banding than '1x(native)' at 4x Internal GPU Resolution) 'disabled' is useful to pair with '32bpp' Internal Color Depth where banding is far less visible or for users who otherwise wish to turn off dithering regardless of color banding at 16bpp. ??? note "*Dithering Pattern - 1x Native (16bpp 4x IR)*" ![](../image/core/beetle_psx_hw/dither_native.png) ??? note "*Dithering Pattern - Internal Resolution (16bpp 4x IR)*" ![](../image/core/beetle_psx_hw/dither_internalres.png) ??? note "*Dithering Pattern - Disabled (16bpp 4x IR)*" ![](../image/core/beetle_psx_hw/dither_off.png) - **Texture Filtering** [beetle_psx_hw_filter] (**nearest**/SABR/xBR/bilinear/3-point/JINC2) OpenGL/Vulkan Only Choose per-texture filtering method. Texture filters can modify or enhance the appearance of 3D polygon textures and 2D elements. 'Nearest' emulates original hardware. 'Bilinear' and '3-Point' are smoothing filters, which reduce pixelation via blurring. 'SABR', 'xBR' and 'JINC2' are upscaling filters, which improve texture fidelity/sharpness at the expense of increased performance requirements. ??? note "*nearest*" ![](../image/core/beetle_psx_hw/nearest.png) ??? note "*SABR*" ![](../image/core/beetle_psx_hw/sabr.png) ??? note "*xBR*" ![](../image/core/beetle_psx_hw/xbr.png) ??? note "*bilinear*" ![](../image/core/beetle_psx_hw/bilinear.png) ??? note "*3-point*" ![](../image/core/beetle_psx_hw/3point.png) ??? note "*JINC2*" ![](../image/core/beetle_psx_hw/jinc2.png) - **Adaptive Smoothing** [beetle_psx_hw_adaptive_smoothing] (**disabled**/enabled) Vulkan Only Enable smoothing of 2D artwork and UI elements without blurring 3D rendered objects. ??? note "*Adaptive smoothing - Off*" ![](../image/core/beetle_psx_hw/smooth_off.png) ??? note "*Adaptive smoothing - On*" ![](../image/core/beetle_psx_hw/smooth_on.png) - **Supersampling (Downsample to Native Resolution)** [beetle_psx_hw_super_sampling] (**disabled**/enabled) Vulkan Only When enabled, renders content at the specified Internal GPU Resolution then downsamples the resulting image to native 240p before shaders and resizing are applied by the frontend. Allows games to be displayed at native (low) resolution but with clean anti-aliased 3D objects. Produces best results when applied to titles that mix 2D and 3D elements such as 3D characters on pre-rendered backgrounds. This option is not to be confused with implicit supersampling provided by rendering at a higher Internal GPU Resolution multiplier then downsampling to the frontend's window scale. ??? note "*Supersampling from 1x Internal Resolution with CRT Royale Shader*" ![](../image/core/beetle_psx_hw/ssaa1x_crt-royale.png) ??? note "*Supersampling from 8x Internal Resolution with CRT Royale Shader*" ![](../image/core/beetle_psx_hw/ssaa8x_crt-royale.png) - **Multi-Sampled Anti Aliasing** [beetle_psx_hw_msaa] (**1x**/2x/4x/8x/16x) Vulkan Only Apply multi-sample anti-aliasing (MSAA) to rendered content. This is a type of spatial anti-aliasing similar to supersampling, but of somewhat lower quality and with (correspondingly) lower performance requirements. Improves the appearance of 3D objects. MSAA may be [clamped internally](https://github.com/libretro/beetle-psx-libretro/pull/469#issue-238935899) at a lower value than what it is set at when running at higher Internal GPU Resolutions. - **MDEC YUV Chroma Filter** [beetle_psx_hw_mdec_yuv] (**disabled**/enabled) Vulkan Only Improves the quality of FMV playblack by smoothing the chroma channel when converting YcBcR to RGB. This reduces macroblocking artefacts (squares/jagged edges) as shown below: ??? note "*MDEC YUV Chroma Filter On/Off Comparison*" ![](../image/core/beetle_psx_hw/mdec-yuv-filter.png) - **Track Textures** [beetle_psx_hw_track_textures] (**disabled**/enabled) Vulkan Only Tracks texture to enable texture dumping/replacing. - **Dump Textures** [beetle_psx_hw_dump_textures] (**disabled**/enabled) Vulkan Only Dumps textures when they are accessed. To dump textures properly, it is necessary to create a folder named -texture-dump/ in the same folder as the game disk. - **Replace Textures** [beetle_psx_hw_replace_textures] (**disabled**/enabled) Vulkan Only Replaces textures with files given in the folder -texture-replacements/ with the same name as dumped textures. **The replacement texture has to be a PNG file with bit depth of a maximum of 8 and the resolution must be a multiple of 2 based on the original texture.** - **Wireframe Mode** [beetle_psx_hw_wireframe] (**disabled**/enabled) OpenGL Only Renders 3D polygons models in outline form without textures or shading. **For debug use only. Leave off for normal usage.** ??? note "*Wireframe mode - On*" ![](../image/core/beetle_psx_hw/wire.png) - **Display Full VRAM** [beetle_psx_hw_display_vram] (**disabled**/enabled) OpenGL/Vulkan Only Visualizes full contents of the emulated PSX VRAM. **For debug use only. Leave off for normal usage.** ??? note "*Display full VRAM - On*" ![](../image/core/beetle_psx_hw/vram.png) - **PGXP Operation Mode** [beetle_psx_hw_pgxp_mode] (**disabled**/memory only/memory + CPU) Enabling the Parallel/Precision Geometry Transform Pipeline (PGXP) allows polygons to be rendered with subpixel precision, eliminating or otherwise diminishing the polygon jitter/wobble visible on original PSX hardware. This distortion results from original hardware using fixed point mathematics when rendering 3D models, thus rounding polygon vertices to the nearest integer pixel. 'disabled' emulates original hardware behavior. 'memory only' mode enables subpixel precision at the cost of increased performance requirements with only minor compatibility issues. 'memory + CPU' mode can further reduce jitter but is highly demanding and is known to cause geometry errors. 'memory only' is recommended for best compatibility. [https://www.youtube.com/watch?v=EYCpd_1lPUc](https://www.youtube.com/watch?v=EYCpd_1lPUc) - **PGXP Vertex Cache** [beetle_psx_hw_pgxp_vertex] (**disabled**/enabled) OpenGL/Vulkan Only Allows PGXP-enhanced polygon vertex coordinates to be cached when PGXP Operation Mode is also enabled. This option improves performance by allowing subpixel-accurate values to be used across successive polygon draws instead of rebasing from native PSX data each time. Allows for better object alignment and may reduce visible seams, but false positives when querying the cache produces graphical glitches in most games. Recommended to leave disabled. - **PGXP Perspective Correct Texturing** [beetle_psx_hw_pgxp_texture] (**disabled**/enabled) OpenGL/Vulkan Only Allows for perspective correct texturing when PGXP Operation Mode is also enabled. Original PSX hardware renders 3D objects with affine texture mapping where texture coordinates are interpolated between polygon vertices in 2D screen space with no consideration of object depth. This causes significant position-dependent distortion and/or blending of textures such as warped lines across floors and walls. PGXP Perspective Correct Texturing accounts correctly for vertex positions in 3D space thereby eliminating this texture distortion at the expense of increased performance requirements. ??? note "*PGXP Texturing - Off*" ![](../image/core/beetle_psx_hw/pgxp_texture_off.jpg) ??? note "*PGXP Texturing - On*" ![](../image/core/beetle_psx_hw/pgxp_texture_on.jpg) - **Display Internal FPS** [beetle_psx_hw_display_internal_fps] (**disabled**/enabled) Displays the frame rate that the emulated PSX is drawing at. Requires onscreen notifications to be enabled in the libretro frontend. Reported values may be inaccurate. ??? note "*Display internal FPS - On*" ![](../image/core/beetle_psx_hw/fps.png) - **Line-to-Quad Hack** [beetle_psx_hw_line_render] (**default**/aggressive/disabled) Certain games employ a special technique for drawing horizontal lines, which involves stretching single-pixel-high triangles across the screen in a manner that causes the PSX hardware to rasterise them as a row of pixels. Examples include Doom/Hexen, and the water effects in Soul Blade. When running such games with an Internal GPU Resolution higher than native, these triangles no longer resolve as a line, causing gaps to appear in the output image. Setting 'Line-to-Quad Hack' to 'Default' solves this issue by detecting small triangles and converting them as required. The 'Aggressive' option will likely introduce visual glitches due to false positives, but is needed for correct rendering of some 'difficult' titles (e.g. Dark Forces, Duke Nukem). - **Frame Duping (Speedup)** [beetle_psx_hw_frame_duping] (**disabled**/enabled) Software Renderer and Vulkan only When enabled, provides a small performance increase by redrawing/reusing the last rendered frame (instead of presenting a new one) if the content of the current frame is unchanged based on the internal fps heuristic. May cause inaccurate behavior or lost animation frames, so it is not recommended to use this unless necessary. - **CPU Dynarec** [beetle_psx_hw_cpu_dynarec] (**disabled**/execute/execute_once/run_interpreter) Dynamically recompile CPU instructions to native instructions. Much faster than interpreter, but CPU timing is less accurate, and may have bugs. - **Dynarec Code Invalidation** [beetle_psx_hw_dynarec_invalidate] (**full**/dma) Some games require Full invalidation, some require DMA Only. This option has no effect when CPU Dynarec is not enabled. - **Dynarec DMA/GPU Event Cycles** [beetle_psx_hw_dynarec_eventcycles] (**128**/256/384/512/640/768/896/1024) Max cycles run by CPU before a GPU or DMA Update is checked, higher number will be faster, has much less impact on beetle interpreter than dynarec. Leave at 128 for default Beetle interpreter behavior when CPU Dynarec is not enabled. - **CPU Frequency Scaling (Overclock)** [beetle_psx_hw_cpu_freq_scale] (50% to 750% in increments of 10%. Default: **100%(native)**) Enable overclocking (or underclocking) of the emulated PSX's CPU. The default frequency of the MIPS R3000A-compatible 32-bit RISC CPU is 33.8688 MHz; running at higher frequencies can eliminate slowdown and improve frame rates in certain games at the expense of increased performance requirements. Note that some games have an internal frame rate limiter and may not benefit from overclocking. It is generally not recommended to adjust this setting as it causes many games or portions of them to run at unintended speeds. This can lead to audio and video desynchronization, among other issues. Leave at default for most games. - **GTE Overclock** [beetle_psx_hw_gte_overclock] (**disabled**/enabled) When enabled, reduces the latency of operations involving the emulated PSX's Geometry Transform Engine (CPU coprocessor used for calculations related to 3D projection - i.e. all 3D graphics) to 1 cycle per instruction and additionally eliminates all memory access or cache fetch latency. For games that make heavy use of the GTE, this can greatly improve frame rate (and frame time) stability at the expense of increased performance requirements. Currently unstable -- leave off if unsure. - **GPU Rasterizer Overclock** [beetle_psx_hw_gpu_overclock] (**1x(native)**/2x/4x/8x/16x/32x) Enables overclocking of the 2D rasterizer contained within the emulated PSX's GPU. Does not improve 3D rendering, and in general has little effect. - **Skip BIOS** [beetle_psx_hw_skip_bios] (**disabled**/enabled) When enabled, skips the PSX BIOS animation normally displayed with starting content. **Enabling this option will cause compatibility issues with a small minority of games (Saga Frontier, PAL copy protected games, etc).** ??? note "*Skip BIOS - Off*" ![](../image/core/beetle_psx_hw/bios.png) - **Core-Reported FPS Timing** [beetle_psx_hw_core_timing_fps] (**force_progressive**/force_interlaced/auto_toggle) Sets FPS timing that the core will report to the frontend. Automatic toggling will allow the core to switch between reporting progressive and interlaced rates, but may cause frontend video/audio driver reinits. Progressive timings are 59.826 for NTSC content and 49.761 for PAL content, and interlaced timings are 59.940 for NTSC content and 50.000 for PAL content. - **Core Aspect Ratio** [beetle_psx_hw_aspect_ratio] (**corrected**/uncorrected/4:3) Set core provided aspect ratio. This setting is ignored when the Widescreen Mode Hack or Display Full VRAM options are enabled. "4:3" forces the core aspect ratio to 4:3 without taking horizontal overscan cropping or visible scanlines into account. The "4:3" setting should not be used and is only provided as a legacy feature for users desiring old incorrect behavior from the core. - **Widescreen Mode Hack** [beetle_psx_hw_widescreen_hack] (**disabled**/enabled) Forces content to be rendered with an aspect ratio of 16:9. Produces best results with fully 3D games. Can cause graphical glitches or alignment/stretching issues in games that mix 3D and 2D elements. Leave off for most games. ??? note "*Widescreen mode hack - Off*" ![](../image/core/beetle_psx_hw/wide_off.png) ??? note "*Widescreen mode hack - On*" ![](../image/core/beetle_psx_hw/wide_on.png) - **Crop Horizontal Overscan** [beetle_psx_hw_crop_overscan] (**enabled**/disabled) By default, Beetle PSX includes horizontal padding (black bars or 'pillarboxes' on either side of the screen) to emulate the same black bars generated in analog video output by real PSX hardware. This horizontal padding can contain garbage pixels that are generated when the game's width mode is smaller than the display area width in the emulated GPU registers. Enabling 'Crop Horizontal Overscan' will remove this potentially glitchy horizontal overscan region. Not all games will benefit from enabling this setting as shown in the examples below. ??? note "*Crop Overscan - Off (Game with Garbage Pixels)*" ![](../image/core/beetle_psx_hw/crop_off.png) ??? note "*Crop Overscan - On (Game with Garbage Pixels)*" ![](../image/core/beetle_psx_hw/crop_on.png) ??? note "*Crop Overscan - Off (Game with No Issues)*" ![](../image/core/beetle_psx_hw/scan_off.png) ??? note "*Crop Overscan - On (Game with No Issues)*" ![](../image/core/beetle_psx_hw/scan_on.png) This option does not affect vertical overscan. Vertical overscan can be cropped using the Initial/Last Scanline core options. - **Additional Cropping** [beetle_psx_hw_image_crop] (**disabled**/1px/2px/3px/4px/5px/6px/7px/8px) Software Renderer Only When 'Crop Horizontal Overscan' is enabled, this option further reduces the width of the cropped image by the specified number of pixels. Note: This can have unintended consequences. While the absolute width is reduced, the resultant video is still scaled to the currently set aspect ratio. Enabling 'Additional Cropping' may therefore cause horizontal stretching. - **Offset Cropped Image** [beetle_psx_hw_image_offset] (**disabled**/-4px/-3px/-2px/-1px/+1px/+2px/+3px/+4px) Software Renderer Only When 'Crop Horizontal Overscan' is enabled, allows the resultant cropped image to be offset horizontally to the right (positive) or left (negative) by the specified number of pixels. May be used to correct alignment issues. - **Horizontal Image Offset (GPU Cycles)** [beetle_psx_hw_image_offset_cycles] (-24 to +24 in increments of 1. Default: **0**) OpenGL/Vulkan Only Horizontally offsets the outputted image by the specified number of GPU timing cycles. Currently only for the hardware renderers and functions like 'Offset Cropped Image', but at a finer granularity and does not require 'Crop Horizontal Overscan' to be enabled for this option to have an effect. - **Initial Scanline - NTSC** [beetle_psx_hw_initial_scanline] (0 to 40 in increments of 1. Default: **0**) Selects the first displayed scanline when running NTSC content. Setting a value greater than 0 will reduce the height of output images by cropping pixels from the topmost edge. May be used to counteract letterboxing built in to some games. - **Last Scanline - NTSC** [beetle_psx_hw_last_scanline] (210 to 239 in increments of 1. Default: **239**) Selects the last displayed scanline when running NTSC content. Setting a value less than 239 will reduce the height of output images by cropping pixels from the bottommost edge. May be used to counteract letterboxing built in to some games. - **Initial Scanline - PAL** [beetle_psx_hw_initial_scanline_pal] (0 to 40 in increments of 1. Default: **0**) Selects the first displayed scanline when running PAL content. Setting a value greater than 0 will reduce the height of output images by cropping pixels from the topmost edge. May be used to counteract letterboxing built in to some games. - **Last Scanline - PAL** [beetle_psx_hw_last_scanline_pal] (230 to 287 in increments of 1. Default: **287**) Selects the last displayed scanline when running PAL content. Setting a value less than 287 will reduce the height of output images by cropping pixels from the bottommost edge. May be used to counteract letterboxing built in to some games. - **CD Access Method (Restart)** [beetle_psx_hw_cd_access_method] (**sync**/async/precache) Selects method used to read data from content disc images. 'sync' emulates original hardware. 'async' can alleviate stuttering on devices with slow storage. 'precache' loads the entire disc image into memory when starting content, incurring a small startup delay. This can improve in-game loading times and eliminate stutters due to emulated CD access, but may cause issues on systems with low memory. - **CD Loading Speed** [beetle_psx_hw_cd_fastload] (**2x(native)**/4x/6x/8x/10x/12x/14x) Selects disk access speed multiplier. This speedhack can greatly reduce loading times at speeds higher than native but is known to introduce texture corruption errors, timing glitches, or loading screen softlocks in many titles. Some games will not work at all if loading speed is not set to native (e.g. Castlevania: Symphony of the Night). **Reduce multiplier value if experiencing loading issues, freezes, etc.** - **Memory Card 0 Method (Restart)** [beetle_psx_hw_use_mednafen_memcard0_method] (**libretro**/mednafen) Choose the savedata format used for Memory Card 0. See the [Saves section](#saves) above for an explanation regarding the libretro and mednafen formats. libretro is recommended, but mednafen may be used for compatibility with the standalone version of Mednafen. The libretro (.srm) and Mednafen (.mcr) formats are internally identical when used with Beetle PSX. Note: This option must be set to 'mednafen' if the Shared Memcards option is enabled. - **Enable Memory Card 1 (Restart)** [beetle_psx_hw_enable_memcard1] (**enabled**/disabled) Selects whether to emulate a second memory card in Slot 1. When disabled, games can only access the memory card in Slot 0. Note: Some games require this option to be disabled for correct operation (e.g. Codename Tenka). - **Shared Memory Cards (Restart)** [beetle_psx_hw_shared_memory_cards] (**disabled**/enabled) When enabled, games will save and load using the same memory card files. Note: The "Memcard 0 Method" option must be set to 'mednafen' for this option to function properly. When disabled, separate memory card files will be generated for each title. This option is useful for games in series such as Suikoden or Arc the Lad that check for save data from previous titles.
| Memcard slot 0 | Memcard slot 1 | |------------------------------------|------------------------------------| | mednafen_psx_libretro_shared.0.mcr | mednafen_psx_libretro_shared.1.mcr |
- **Analog Self-Calibration** [beetle_psx_hw_analog_calibration] (**disabled**/enabled) When enabled, monitors the max values reached by the input, using it as a calibration heuristic which then scales the analog coordinates sent to the emulator accordingly. For best results, rotate the sticks at max amplitude for the algorithm to get a good estimate of the scaling factor, otherwise it will adjust while playing. While modern analog sticks have circular logical ranges, older analog sticks such as those on the DualShock have logical ranges closer to squares and can report larger values at the intercardinal directions than modern analog sticks can. Games that expect these larger values will have issues controlling with modern analog sticks, which this option can solve by scaling modern analog stick values up. - **Enable DualShock Analog Mode Toggle** [beetle_psx_hw_analog_toggle] (**disabled**/enabled) When the input device type is set to DualShock, this option determines whether or not the Analog Button on that device can be toggled. When this option is disabled, the DualShock input device will be locked in Analog Mode where the analog sticks are on. When this option is enabled, the DualShock input device can be toggled between Digital Mode (analog sticks off) and Analog Mode (analog sticks on) much like real hardware by pressing and holding START+SELECT+L1+L2+R1+R2 for one second in lieu of a dedicated Analog Button. Note: Some games may not respond to input when the DualShock is in Analog Mode. Either enable Analog Button Toggle and toggle the DualShock to Digital Mode or change your input device type to PlayStation Controller. - **Port 1: Multitap Enable** [beetle_psx_hw_enable_multitap_port1] (**disabled**/enabled) Enables/Disables multitap functionality on port 1. - **Port 2: Multitap Enable** [beetle_psx_hw_enable_multitap_port2] (**disabled**/enabled) Enables/Disables multitap functionality on port 2. - **Gun Input Mode** [beetle_psx_hw_gun_input_mode] (**lightgun**/touchscreen) When device type is set to 'Guncon / G-Con 45' or 'Justifier', specify whether to use a mouse-controlled 'Light Gun' or 'Touchscreen' input. - **Gun Cursor** [beetle_psx_hw_gun_cursor] (**cross**/dot/off) Selects the gun cursor to be displayed on screen while using the the 'Guncon / G-Con 45' and 'Justifier' input device types. When disabled, cross hairs are always hidden. ??? note "*Gun Cursor - Cross*" ![](../image/core/beetle_psx_hw/cursor_cross.png) ??? note "*Gun Cursor - Dot*" ![](../image/core/beetle_psx_hw/cursor_dot.png) ??? note "*Gun Cursor - Off*" ![](../image/core/beetle_psx_hw/cursor_off.png) - **Mouse Sensitivity** [beetle_psx_hw_mouse_sensitivity] (5% to 200% in increments of 5%. Default: **100%**) Configure the response of the 'Mouse' input device type. - **NegCon Twist Response** [beetle_psx_hw_negcon_response] (**linear**/quadratic/cubic) Specifies the analog response when using a RetroPad left analog stick to simulate the 'twist' action of emulated [neGcon Controllers](https://en.wikipedia.org/wiki/NeGcon). 'linear': Analog stick displacement is mapped linearly to negCon rotation angle. 'quadratic': Analog stick displacement is mapped quadratically to negCon rotation angle. This allows for greater precision when making small movements with the analog stick. 'cubic': Analog stick displacement is mapped cubically to negCon rotation angle. This allows for even greater precision when making small movements with the analog stick, but 'exaggerates' larger movements. !!! attention A linear response is not recommended when using standard gamepad devices. The negCon 'twist' mechanism is substantially different from conventional analog sticks; linear mapping over-amplifies small displacements of the stick, impairing fine control. A linear response is only appropriate when using racing wheel peripherals. In most cases, the 'quadratic' option should be selected. This provides effective compensation for the physical differences between real/emulated hardware and is the closest approximation of real hardware, enabling smooth/precise analog input. - **NegCon Twist Deadzone** [beetle_psx_hw_negcon_deadzone] (**0%**/5%/10%/15%/20%/25%/30%) Sets the deadzone of the RetroPad left analog stick when simulating the 'twist' action of emulated [neGcon Controllers](https://en.wikipedia.org/wiki/NeGcon). Used to eliminate drift/unwanted input. !!! attention Most (all?) negCon compatible titles provide in-game options for setting a 'twist' deadzone value. To avoid loss of precision, the in-game deadzone should *always* be set to zero. Any analog stick drift should instead be accounted for by configuring the 'NegCon Twist Deadzone' core option. This is particularly important when 'NegCon Twist Response' is set to 'quadratic' or 'cubic'. Xbox gamepads typically require a deadzone of 15-20%. Many Android-compatible bluetooth gamepads have an internal 'hardware' deadzone, allowing the deadzone value here to be set to 0%. For convenience, it is recommended to make use of the 'Options → Analog Setting 1P' menu of [Gran Turismo](https://en.wikipedia.org/wiki/Gran_Turismo_(video_game)) when calibrating the 'NegCon Twist Deadzone'. This provides a clear and precise representation of 'real' controller input values. ## User 1 - 8 device types The Beetle PSX HW core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): - None - Input disabled. - [**PlayStation Controller**](https://en.wikipedia.org/wiki/PlayStation_Controller) - Joypad - PlayStation Controller (SCPH-1080) - [DualShock](https://en.wikipedia.org/wiki/DualShock) - Joypad - DualShock (SCPH-1200) - [Analog Controller](https://en.wikipedia.org/wiki/Dual_Analog_Controller) - Joypad - PlayStation Dual Analog Controller(SCPH-1180) - [Analog Joystick](https://en.wikipedia.org/wiki/PlayStation_Analog_Joystick) - Joypad - PlayStation Analog Joystick (SCPH-1110) - [Guncon / G-Con 45](https://en.wikipedia.org/wiki/GunCon) - Lightgun - Namco Gun Controller (SLEH-00007) - [Justifier](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - Konami Justifier lightgun peripheral (SLEH-00005, SLUH-00017) - [Mouse](https://en.wikipedia.org/wiki/PlayStation_Mouse) - Mouse - PlayStation Mouse (SCPH-1090, SCPH-1030) - [neGcon](https://en.wikipedia.org/wiki/NeGcon) - Joypad - Namco third party controller ## Rumble support Rumble only works in the Beetle PSX HW core when - The content being ran has rumble support. - The frontend being used has rumble support. - The joypad device being used has rumble support. - The corresponding user's device type is set to **DualShock** ## Multitap support ['Port 1: Multitap enable' and 'Port 2: Multitap enable' core options](#core-options). ## Joypad ![](../image/controller/psx.png) | User 1 - 8 input descriptors | RetroPad Inputs | PlayStation Controller Inputs | DualShock Inputs | Analog Controller Inputs | Analog Joystick Inputs | neGcon Inputs | |-------------------------------|----------------------------------------------|------------------------------------------------|-------------------------------------------------|-------------------------------------------------|------------------------------------------------|---------------------------------| | Cross | ![](../image/retropad/retro_b.png) | ![](../image/Button_Pack/PS3/PS3_Cross.png) | ![](../image/Button_Pack/PS3/PS3_Cross.png) | ![](../image/Button_Pack/PS3/PS3_Cross.png) | ![](../image/Button_Pack/PS3/PS3_Cross.png) | Analog button I | | Square | ![](../image/retropad/retro_y.png) | ![](../image/Button_Pack/PS3/PS3_Square.png) | ![](../image/Button_Pack/PS3/PS3_Square.png) | ![](../image/Button_Pack/PS3/PS3_Square.png) | ![](../image/Button_Pack/PS3/PS3_Square.png) | Analog button II | | Select | ![](../image/retropad/retro_select.png) | ![](../image/Button_Pack/PS3/PS3_Select.png) | ![](../image/Button_Pack/PS3/PS3_Select.png) | ![](../image/Button_Pack/PS3/PS3_Select.png) | ![](../image/Button_Pack/PS3/PS3_Select.png) | | | Start | ![](../image/retropad/retro_start.png) | ![](../image/Button_Pack/PS3/PS3_Start.png) | ![](../image/Button_Pack/PS3/PS3_Start.png) | ![](../image/Button_Pack/PS3/PS3_Start.png) | ![](../image/Button_Pack/PS3/PS3_Start.png) | Start | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Up.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Up.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Up.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Up.png) | D-Pad Up | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Down.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Down.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Down.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Down.png) | D-Pad Down | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Left.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Left.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Left.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Left.png) | D-Pad Left | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Right.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Right.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Right.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Right.png) | D-Pad Right | | Circle | ![](../image/retropad/retro_a.png) | ![](../image/Button_Pack/PS3/PS3_Circle.png) | ![](../image/Button_Pack/PS3/PS3_Circle.png) | ![](../image/Button_Pack/PS3/PS3_Circle.png) | ![](../image/Button_Pack/PS3/PS3_Circle.png) | A | | Triangle | ![](../image/retropad/retro_x.png) | ![](../image/Button_Pack/PS3/PS3_Triangle.png) | ![](../image/Button_Pack/PS3/PS3_Triangle.png) | ![](../image/Button_Pack/PS3/PS3_Triangle.png) | ![](../image/Button_Pack/PS3/PS3_Triangle.png) | B | | L1 | ![](../image/retropad/retro_l1.png) | ![](../image/Button_Pack/PS3/PS3_L1.png) | ![](../image/Button_Pack/PS3/PS3_L1.png) | ![](../image/Button_Pack/PS3/PS3_L1.png) | ![](../image/Button_Pack/PS3/PS3_L1.png) | Left shoulder button (analog) | | R1 | ![](../image/retropad/retro_r1.png) | ![](../image/Button_Pack/PS3/PS3_R1.png) | ![](../image/Button_Pack/PS3/PS3_R1.png) | ![](../image/Button_Pack/PS3/PS3_R1.png) | ![](../image/Button_Pack/PS3/PS3_R1.png) | Right shoulder button (digital) | | L2 | ![](../image/retropad/retro_l2.png) | ![](../image/Button_Pack/PS3/PS3_L2.png) | ![](../image/Button_Pack/PS3/PS3_L2.png) | ![](../image/Button_Pack/PS3/PS3_L2.png) | ![](../image/Button_Pack/PS3/PS3_L2.png) | Analog button II | | R2 | ![](../image/retropad/retro_r2.png) | ![](../image/Button_Pack/PS3/PS3_R2.png) | ![](../image/Button_Pack/PS3/PS3_R2.png) | ![](../image/Button_Pack/PS3/PS3_R2.png) | ![](../image/Button_Pack/PS3/PS3_R2.png) | Analog button I | | L3 | ![](../image/retropad/retro_l3.png) | | ![](../image/Button_Pack/PS3/PS3_L3.png) | | | | | R3 | ![](../image/retropad/retro_r3.png) | | ![](../image/Button_Pack/PS3/PS3_R3.png) | | | | | Left Analog X | ![](../image/retropad/retro_left_stick.png) X | | ![](../image/Button_Pack/PS3/PS3_Left_Stick.png) | ![](../image/Button_Pack/PS3/PS3_Left_Stick.png) | Left Joystick X | Twist | | Left Analog Y | ![](../image/retropad/retro_left_stick.png) Y | | ![](../image/Button_Pack/PS3/PS3_Left_Stick.png) | ![](../image/Button_Pack/PS3/PS3_Left_Stick.png) | Left Joystick Y | | | Right Analog X | ![](../image/retropad/retro_right_stick.png) X | | ![](../image/Button_Pack/PS3/PS3_Right_Stick.png) | ![](../image/Button_Pack/PS3/PS3_Right_Stick.png) | Right Joystick X | | | Right Analog Y | ![](../image/retropad/retro_right_stick.png) Y | | ![](../image/Button_Pack/PS3/PS3_Right_Stick.png) | ![](../image/Button_Pack/PS3/PS3_Right_Stick.png) | Right Joystick Y | | ## Mouse | RetroMouse Inputs | Mouse Inputs | |-----------------------------------------------------|--------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | Mouse Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | Mouse Right Button | ## Lightgun | RetroLightgun Inputs | Guncon / G-Con 45 Inputs | Justifier Inputs | |------------------------------------------------------|-----------------------------|---------------------| | ![](../image/retromouse/retro_mouse.png) Gun Crosshair | Guncon / G-Con 45 Crosshair | Justifier Crosshair | | Gun Trigger | Guncon / G-Con 45 Trigger | Justifier Trigger | | Gun Reload | Guncon / G-Con 45 Reload | Justifier Reload | | Gun Aux A | Guncon / G-Con 45 A | Justifier Aux | | Gun Aux B | Guncon / G-Con 45 B | | | Gun Start | | Justifier Start | ## Compatibility **Expect bugs with hardware renderer enhancements.** When using the run-ahead latency reduction feature, the "second instance" setting will break the hardware renderer. Hardware renderer currently has a number of issues with interlacing shaders and outputting on CRTs. Use the software renderer for the time being. A list of known emulation bugs when using the software renderer can be found here [https://forum.fobby.net/index.php?t=msg&th=1114&start=0&](https://forum.fobby.net/index.php?t=msg&th=1114&start=0&) Issue tracker for the hardware renderer can be found here [https://github.com/libretro/beetle-psx-libretro/issues](https://github.com/libretro/beetle-psx-libretro/issues) ## External Links - [Official Mednafen Website](https://mednafen.github.io/) - [Official Mednafen Downloads](https://mednafen.github.io/releases/) - [Beetle PSX HW Libretro Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mednafen_psx_hw_libretro.info) - [Beetle PSX HW Libretro Github Repository](https://github.com/libretro/beetle-psx-libretro) - [Report Beetle PSX HW Core Issues Here](https://github.com/libretro/beetle-psx-libretro/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0Ie3vgCI_d3bslkumKT06AQa) ## Libretro PSX cores - [PlayStation (Beetle PSX)](beetle_psx.md) - [PlayStation (PCSX ReARMed)](pcsx_rearmed.md) ================================================ FILE: docs/library/beetle_saturn.md ================================================ # Sega - Saturn (Beetle Saturn) ## Background This is fork of Mednafen Saturn. It has been ported to the libretro API. It currently runs on Linux, OSX and Windows. The Beetle Saturn core has been authored by - [Mednafen Team](https://mednafen.github.io/) The Beetle Saturn core is licensed under - [GPLv2](https://github.com/libretro/beetle-saturn-libretro/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Beetle Saturn core have the following file extensions: - .cue - .toc - .m3u - .ccd - .chd RetroArch database(s) that are associated with the Beetle Saturn core: - [Sega - Saturn](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20Saturn.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. !!! attention The King of Fighters '95 and Ultraman: Hikari no Kyojin Densetsu ROM Cartridges can be manually selected with the ['Cartridge' core option](#core-options). | Filename | Description | md5sum | |:----------------:|:--------------------------------------------------------------------------:|:--------------------------------:| | sega_101.bin | Saturn JP BIOS - Required for JP games | 85ec9ca47d8f6807718151cbcca8b964 | | mpr-17933.bin | Saturn US.mdEU BIOS - Required for US/EU games | 3240872c70984b6cbfda1586cab68dbe | | mpr-18811-mx.ic1 | The King of Fighters '95 ROM Cartridge - Required for this game | 255113ba943c92a54facd25a10fd780c | | mpr-19367-mx.ic1 | Ultraman: Hikari no Kyojin Densetsu ROM Cartridge - Required for this game | 1cd19988d1d72a3e7caa0b73234c96b4 | ## Features Frontend-level settings or features that the Beetle Saturn core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | - | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✔ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Directories The Beetle Saturn core's library name is 'Beetle Saturn' The Beetle Saturn core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:------:|:------------------------------------:| | *.bcr | External cartridge backup save | | *.bkr | Internal save | | *.smpc | SMPC's emulated Real-Time Clock save | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ## Geometry and timing - The Beetle Saturn core's core provided FPS is 59.83 for NTSC games and 49.92 for PAL games - The Beetle Saturn core's core provided sample rate is 44100 Hz - The Beetle Saturn core's base width is 320 - The Beetle Saturn core's base height is 240 - The Beetle Saturn core's max width is 704 - The Beetle Saturn core's max height is 576 - The Beetle Saturn core's core provided aspect ratio is 4/3 ## Loading Saturn Sega content Beetle Saturn needs a cue-sheet that points to an image file. A cue sheet, or cue file, is a metadata file which describes how the tracks of a CD or DVD are laid out. If you have e.g. `foo.bin`, you should create a text file and save it as `foo.cue`. If you're playing a single-track Saturn game, then the cue file contents should look like this: `foobin.cue` ``` FILE "foo.bin" BINARY TRACK 01 MODE1/2352 INDEX 01 00:00:00 ``` After that, you can load the `foo.cue` file in RetroArch with the Beetle Saturn core. !!! attention Certain Saturn games are multi-track, so their .cue files might be more complicated. ## Multiple-disk games If foo is a multiple-disk game, you should have .cue files for each one, e.g. `foo (Disc 1).cue`, `foo (Disc 2).cue`, `foo (Disc 3).cue`. To take advantage of Beetle Saturn's Disk Control feature for disk swapping, an index file (a m3u file) should be made. Create a text file and save it as `foo.m3u`. Then enter your game's .cue files on it. The m3u file contents should look something like this: `foo.m3u` ``` foo (Disc 1).cue foo (Disc 2).cue foo (Disc 3).cue ``` ## Swapping disks Swapping disks follows this procedure 1. Open tray (Disk Cycle Tray Status) 2. Change the Disk Index to the disk you want to swap to. 3. Close tray (Disk Cycle Tray Status) 4. Return to the game and wait a few seconds to let it take effect After that, you can load the `foo.m3u` file in RetroArch with the Beetle Saturn core. ## Core options The Beetle Saturn core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **System Region** [beetle_saturn_region] (**Auto Detect**|Japan|North America|Europe|South Korea|Asia (NTSC)|Asia (PAL)|Brazil|Latin America) Choose which region the system is from. - **Cartridge** [beetle_saturn_cart] (**Auto Detect**|None|Backup Memory|Extended RAM (1MB)|Extended RAM (4MB)|The King of Fighters '95|Ultraman: Hikari no Kyojin Densetsu) A list of games that require a cartridge can be found [here](https://www.satakore.com/cartridge.php). - **6Player Adaptor on Port 1** [beetle_saturn_multitap_port1] (**disabled**|enabled) Enable [multitap](https://segaretro.org/Saturn_6_Player_Adaptor) on Saturn port 1. - **6Player Adaptor on Port 2** [beetle_saturn_multitap_port2] (**disabled**|enabled) Enable [multitap](https://segaretro.org/Saturn_6_Player_Adaptor) on Saturn port 2. - **Analog Stick Deadzone** [beetle_saturn_analog_stick_deadzone] (**15%**|20%|25%|30%|0%|5%|10%) Configure the '3D Control Pad' Device Type's analog deadzone. - **Trigger Deadzone** [beetle_saturn_trigger_deadzone] (**15%**|20%|25%|30%|0%|5%|10%) Configure the '3D Control Pad' Device Type's trigger deadzone. - **Mouse Sensitivity** [beetle_saturn_mouse_sensitivity] (5% to 200% in increments of 5%. **100% is default**) Configure the 'Mouse' device type's sensitivity. - **Gun Crosshair** [beetle_saturn_virtuagun_crosshair] (**Cross**|Dot|Off) Choose the crosshair for the 'Stunner' and 'Virtua Gun' device types. Setting it to Off disables the crosshair. ??? note "Gun - Crosshair - Cross" ![](../image/core/beetle_saturn/cross.png) ??? note "Gun - Crosshair - Dot" ![](../image/core/beetle_saturn/dot.png) ??? note "Gun - Crosshair - Off" ![](../image/core/beetle_saturn/off.png) - **CD Image Cache (restart)** [beetle_saturn_cdimagecache] (**disabled**|enabled) Loads the complete image in memory at startup. Can potentially decrease loading times at the cost of increased startup time. Requires a restart in order for a change to take effect. - **Mid-frame Input Synchronization** [beetle_saturn_midsync] (**disabled**|enabled) Mid-frame synchronization can reduce input latency, but it will increase CPU requirements. - **Automatically set RTC on game load** [beetle_saturn_autortc] (**enabled**|disabled) Automatically set the SMPC's emulated Real-Time Clock to the host system's current time and date upon game load. - **BIOS language** [beetle_saturn_autortc_lang] (**english**|german|french|spanish|italian|japanese) Self explanatory. Also affects language used in some games (e.g. the European release of "Panzer Dragoon"). - **Horizontal Overscan Mask** [beetle_saturn_horizontal_overscan] (0 to 60 in increments of 2. **0 is default**) Self-explanatory. - **Initial scanline** [beetle_saturn_initial_scanline] (0 to 40 in increments of 1. **0 is default**) Adjust the first displayed scanline in NTSC mode. - **Last scanline** [beetle_saturn_last_scanline] (210 to 239 in increments of 1. **239 is default**) Adjust the last displayed scanline in NTSC mode. - **Initial scanline PAL** [beetle_saturn_initial_scanline_pal] (0 to 60 in increments of 1. **16 is default**) Adjust the first displayed scanline in NTSC mode. - **Last scanline PAL** [beetle_saturn_last_scanline_pal] (230 to 287 in increments of 1. **271 is default**) Adjust the last displayed scanline in PAL mode. - **Enable Horizontal Blend(blur)** [beetle_saturn_horizontal_blend] (**disabled**|enabled) Enable horizontal blend(blur) filter. Has a more noticeable effect with the Saturn's higher horizontal resolution modes(640/704). ??? note "Enable Horizontal Blend(blur) - Off" ![](../image/core/beetle_saturn/blend_off.png) ??? note "Enable Horizontal Blend(blur) - On" ![](../image/core/beetle_saturn/blend_on.png) ## User 1 - 12 device types The Beetle Saturn core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): - None - Input disabled. - [**Control Pad**](http://segaretro.org/Control_Pad_(Saturn)) - Joypad - [3D Control Pad](http://segaretro.org/3D_Control_Pad) - Analog - [Arcade Racer](http://segaretro.org/Arcade_Racer_Joystick) - Analog - [Mission Stick](https://segaretro.org/Sega_Mission_Stick) - Analog - [Mouse](http://segaretro.org/Shuttle_Mouse) - Mouse - [Stunner](http://segaretro.org/Virtua_Gun) - Lightgun - [Twin-Stick](https://segaretro.org/Saturn_Twin-Stick) - Analog - [Virtua Gun](https://segaretro.org/Virtua_Gun) - Lightgun - [Dual Mission Sticks](https://segaretro.org/Sega_Mission_Stick) - Analog - Panzer Dragoon Zwei only ## Multitap Activating multitap support in compatible games can be configured by the ['6Player Adaptor on Port 1' and '6Player Adaptor on Port 2' core options](#core-options). ## Joypad ![](../image/controller/saturn.png) | RetroPad Inputs | User 1 - 12 input descriptors | Control Pad | 3D Control Pad | Arcade Racer | Mission Stick | Twin-Stick | Dual Mission Sticks | |------------------------------------------------|-------------------------------|--------------|----------------|---------------------------|----------------|---------------------|----------------------| | ![](../image/retropad/retro_b.png) | A Button | A Button | A Button | A Button | A Button | | A Button | | ![](../image/retropad/retro_y.png) | X Button | X Button | X Button | X Button | X Button | | X Button | | ![](../image/retropad/retro_select.png) | Mode Switch | | Mode Switch | | | | | | ![](../image/retropad/retro_start.png) | Start Button | Start Button | Start Button | Start Button | Start Button | Start Button | Start Button | | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | D-Pad Up | D-Pad Up | | | | | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | D-Pad Down | D-Pad Down | | | | | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | D-Pad Left | D-Pad Left | | | | | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | D-Pad Right | D-Pad Right | | | | | | ![](../image/retropad/retro_a.png) | B Button | B Button | B Button | B Button | B Button | | B Button | | ![](../image/retropad/retro_x.png) | Y Button | Y Button | Y Button | Y Button | Y Button | | Y Button | | ![](../image/retropad/retro_l1.png) | Z Button | Z Button | Z Button | Z Button | Z Button | Left Stick Button | Z Button | | ![](../image/retropad/retro_r1.png) | C Button | C Button | C Button | C Button | C Button | Right Stick Button | C Button | | ![](../image/retropad/retro_l2.png) | L Button | L Button | L Button | Left shift paddle (Up) | L Button | Left Stick Trigger | L Button | | ![](../image/retropad/retro_r2.png) | R Button | R Button | R Button | Right shift paddle (Down) | R Button | Right Stick Trigger | R Button | | ![](../image/retropad/retro_r3.png) | | | | | Throttle latch | | Throttle latch | | ![](../image/retropad/retro_left_stick.png) X | Analog X | | Analog X | Analog wheel | Analog Stick X | Left Stick X | Left Analog Stick X | | ![](../image/retropad/retro_left_stick.png) Y | Analog Y | | Analog Y | | Analog Stick Y | Left Stick Y | Left Analog Stick Y | | ![](../image/retropad/retro_right_stick.png) X | Analog X (Right) | | | | | Right Stick X | Right Analog Stick X | | ![](../image/retropad/retro_right_stick.png) Y | Analog Y (Right) | | | | Throttle | Right Stick Y | Right Analog Stick Y | ## Mouse | RetroMouse Inputs | Mouse | |-------------------------------------------------------|--------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | Mouse A | | ![](../image/retromouse/retro_right.png) Mouse 2 | Mouse B | | ![](../image/retromouse/retro_middle.png) Mouse 3 | Mouse C | | Mouse 4 | Mouse Start | | Mouse 5 | Mouse Start | ## Lightgun | RetroLightgun Inputs | Stunner | Virtua Gun | |--------------------------------------------------------|-------------------|----------------------| | ![](../image/retromouse/retro_mouse.png) Gun Crosshair | Stunner Crosshair | Virtua Gun Crosshair | | Gun Trigger | Stunner Trigger | Virtua Gun Trigger | | Gun Reload | Stunner Reload | Virtua Gun Reload | | Gun Start | Stunner Start | Virtua Gun Start | ## External Links - [Official Mednafen Website](https://mednafen.github.io/) - [Official Mednafen Downloads](https://mednafen.github.io/releases/) - [Libretro Beetle Saturn Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mednafen_saturn_libretro.info) - [Libretro Beetle Saturn Github Repository](https://github.com/libretro/beetle-saturn-libretro) - [Report Libretro Beetle Saturn Core Issues Here](https://github.com/libretro/beetle-saturn-libretro/issues) ## Saturn - [Sega - Saturn (Beetle Saturn)](beetle_saturn.md) - [Sega - Saturn/ST-V (Kronos)](kronos.md) - [Sega - Saturn (Yabause)](yabause.md) - [Sega - Saturn (YabaSanshiro)](yabasanshiro.md) ================================================ FILE: docs/library/beetle_sgx.md ================================================ # NEC - PC Engine SuperGrafx (Beetle SuperGrafx) ## Background Standalone port of Mednafen PCE Fast to libretro. The Beetle SuperGrafx core has been authored by - [Mednafen Team](https://mednafen.github.io/) The Beetle SuperGrafx core is licensed under - [GPLv2](https://github.com/libretro/beetle-supergrafx-libretro/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Required or optional firmware files go in RetroArch's system directory. !!! attention Which PCE CD BIOS file the Beetle SuperGrafx core will use can be configured by the ['CD BIOS' core option](#core-options). !!! attention Any CD-ROM System BIOS will work, but some of them are known to be incompatible with certain games. | Filename | Description | md5sum | |:-------------:|:-------------------------------------:|:--------------------------------:| | syscard3.pce | Super CD-ROM2 System V3.xx - Required | 38179df8f4ac870017db21ebcbf53114 | | syscard2.pce | CD-ROM System V2.xx - Optional | | | syscard1.pce | CD-ROM System V1.xx - Optional | | | gexpress.pce | Game Express CD Card - Optional | | ## Extensions Content that can be loaded by the Beetle SuperGrafx core have the following file extensions: - .pce - .sgx - .cue - .ccd - .chd RetroArch database(s) that are associated with the Beetle SuperGrafx core: - [NEC - PC Engine - TurboGrafx 16](https://github.com/libretro/libretro-database/blob/master/rdb/NEC%20-%20PC%20Engine%20-%20TurboGrafx%2016.rdb) - [NEC - PC Engine CD - TurboGrafx-CD](https://github.com/libretro/libretro-database/blob/master/rdb/NEC%20-%20PC%20Engine%20CD%20-%20TurboGrafx-CD.rdb) - [NEC - PC Engine SuperGrafx](https://github.com/libretro/libretro-database/blob/master/rdb/NEC%20-%20PC%20Engine%20SuperGrafx.rdb) ## Features Frontend-level settings or features that the Beetle Saturn core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✔ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Directories The Beetle SuperGrafx core's library name is 'Beetle SuperGrafx' The Beetle SuperGrafx core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:-----------:| | *.srm | Save | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ## Geometry and timing - The Beetle SuperGrafx core's core provided FPS is 59.82 - The Beetle SuperGrafx core's core provided sample rate is 44100 Hz - The Beetle SuperGrafx core's base width is 512 - The Beetle SuperGrafx core's base height is dependent on the ['Initial scanline' and 'Last scanline' core options](#core-options). - The Beetle SuperGrafx core's max width is 512 - The Beetle SuperGrafx core's max height is 243 - The Beetle SuperGrafx core's core provided aspect ratio is dependent on the ['Aspect Ratio' core option](#core-options). ## Loading PC Engine CD content To load PC Engine CD content, Beetle SuperGrafx needs a cue-sheet that points to an image file. A cue sheet, or cue file, is a metadata file which describes how the tracks of a CD or DVD are laid out. If you have e.g. `foo.bin`, you should create a text file and save it as `foo.cue`. If you're playing a single-track Saturn game, then the cue file contents should look like this: `foobin.cue` ``` FILE "foo.bin" BINARY TRACK 01 MODE1/2352 INDEX 01 00:00:00 ``` After that, you can load the `foo.cue` file in RetroArch with the Beetle SuperGrafx core. !!! warning "" Certain PC Engine content are multi-track, so their .cue files might be more complicated. ISO + OGG and ISO + WAV format games are supported, but they require a properly formatted cue sheet. For iso files, tracks should be denoted as BINARY, for ogg files, they should be denoted as OGG, and for wav files, they should be denoted as WAVE. ## CHD Alternatively to using cue sheets with .bin/.iso files, you can convert your games to .chd (MAME Compressed Hunks of Data) to reduce file sizes and neaten up your game folder. To convert content to CHD format, use the chdman tool found inside the latest MAME distribution and point it to a .cue file, like so: ``` chdman createcd --input foo.cue --output foo.chd ``` ## Core options The Beetle SuperGrafx core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **CD Image Cache (Restart)** [sgx_cdimagecache] (**disabled**|enabled) Loads the complete image in memory at startup. Can potentially decrease loading times at the cost of increased startup time. - **CD Bios (Restart)** [sgx_cdbios] (**System Card 3**|Games Express|System Card 1|System Card 2) Select which PC Engine CD BIOS to use. Look at the [BIOS section](#core-options) for more information. - **Force SuperGrafx Emulation (Restart)** [sgx_forcesgx] (**disabled**|enabled) This is helpful to run homebrew games or isolate games that will not run in SuperGrafx mode. (like Space Harrier). **Savestates are not compatible with each mode. It's better to leave this option at default (Off) unless needed. Known Supergrafx games (like Dai-Makaimura, Aldyns) will automatically switch to SuperGrafx regardless of this option.** - **No Sprite Limit** [sgx_nospritelimit] (**disabled**|enabled) Remove 16-sprites-per-scanline hardware limit. - **CPU Overclock Multiplier (Restart)** [sgx_ocmultiplier] (**1**|2|3|4|5|6|7|8|9|10|20|30|40|50) Overclock the emulated CPU. - **Horizontal Overscan (352 Width Mode Only)** [sgx_hoverscan] (300 to 352 in increments of 2. **352 in default**.) Modify the horizontal overscan. - **Initial scanline** [sgx_initial_scanline] (0 to 40 in increments of 1. **3 is default.**) Adjust first display scanline. - **Last scanline** [sgx_last_scanline] (208 to 242 in increments of 1. **242 is default.**) Adjust last display scanline. - **(CD) CDDA Volume %** [sgx_cddavolume] (0 to 200 in increments of 10. **100 is default**.) Modify CDDA Volume %. - **(CD) ADPCM Volume %** [sgx_adpcmvolume] (0 to 200 in increments of 10. **100 is default**.) Modify ADPCM Volume %. - **(CD) CD PSG Volume %;** [sgx_cdpsgvolume] (0 to 200 in increments of 10. **100 is default**.) Modify CD PSG Volume %. - **(CD) CD Speed** [sgx_cdspeed] (**1**|2|4|8) Set the speed of the emulated CD drive. - **Turbo Delay** [sgx_turbo_delay] (**3**|4|5|6|7|8|9|10|11|12|13|14|15|30|60|2) Adjust turbo delay. - **Turbo ON/OFF Toggle** [sgx_turbo_toggle] (**disabled**|enabled) Enables Turbo ON/OFF inputs. Look at the [Joypad section](#joypad) for more information. - **Alternate Turbo Hotkey** [sgx_turbo_toggle_hotkey] (**disabled**|enabled) Enables Alternate Turbo ON/OFF inputs. You can avoid remapping Button III and IV when switching to 6-button gamepad mode with this. Look at the [Joypad section](#joypad) for more information. - **Disable Soft Reset (RUN+SELECT)** [sgx_disable_softreset] (**disabled**|enabled) Pressing RUN and SELECT simultaneously on PCE gamepad will SOFT RESET the console. This is a default hardware behaviour. Set this to enabled if you want the soft reset functionality turned off. - **Allow Opposing Directions** [sgx_up_down_allowed] (**disabled**|enabled) Enabling this will allow pressing / quickly alternating / holding both left and right (or up and down in some games) directions at the same time. This may cause movement based glitches to occur in certain games. It's best to keep this core option disabled. - **Mouse Sensitivity** [sgx_mouse_sensitivity] (1.00 to 5.00 in increments of 0.25. **1.00 is default**.) Configure the PCE Mouse device type's sensitivity. - **Aspect Ratio** [sgx_aspect_ratio] (**auto**|6:5|4:3) Select an auto (PAR) aspect ratio, or a 6:5 (Used to be default) aspect ratio, or a 4:3 TV aspect ratio. **When using games that constantly switches between 256 and 352 modes and using auto aspect, its best to set Horizontal width to 342 as to minimize resizing and extra black lines since this width is in ratio of 256-width mode(or something like that, just test with Asuka 100% which is one of the game that switches between these modes)** ## User 1 - 5 device types The Beetle SuperGrafx core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): - None - Input is disabled. - **PCE Joypad** - Joypad - PCE Mouse - Mouse ## Joypad - Use the Mode Switch input to switch between button modes. - The regular Turbo inputs for 2-button mode are only active when the ['Turbo ON/OFF Toggle' core option](#core-options) is set to On. - The Alternate Turbo inputs for 2-button mode are only active when the ['Turbo ON.mdOFF Toggle' core option](#core-options) is set to On and the ['Alternate Turbo Hotkey' core option](#core-options) is set to On. | RetroPad Inputs | User 1 - 5 input descriptors | PCE Joypad 2-button | PCE Joypad 6-button | |------------------------------------------------|------------------------------|---------------------------|---------------------| | ![](../image/retropad/retro_b.png) | II | II | II | | ![](../image/retropad/retro_y.png) | III | II Turbo On/Off | III | | ![](../image/retropad/retro_select.png) | Select | Select | Select | | ![](../image/retropad/retro_start.png) | Run | Run | Run | | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | D-Pad Up | D-Pad Up | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | D-Pad Down | D-Pad Down | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | D-Pad Left | D-Pad Left | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | D-Pad Right | D-Pad Right | | ![](../image/retropad/retro_a.png) | I | I | I | | ![](../image/retropad/retro_x.png) | IV | I Turbo On/Off | IV | | ![](../image/retropad/retro_l1.png) | V | | V | | ![](../image/retropad/retro_r1.png) | VI | | VI | | ![](../image/retropad/retro_l2.png) | Mode Switch | Mode Switch | Mode Switch | | ![](../image/retropad/retro_l3.png) | | Alternate II Turbo On/Off | | | ![](../image/retropad/retro_r3.png) | | Alternate I Turbo On/Off | | ## Mouse | RetroMouse Inputs | PCE Mouse | |-------------------------------------------------------|------------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | PCE Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | PCE Mouse Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | PCE Mouse Right Button | | ![](../image/retromouse/retro_middle.png) Mouse 3 | PCE Mouse Start Button | | ![](../image/retropad/retro_select.png) | Select (Joypad) | | ![](../image/retropad/retro_start.png) | Start (Joypad) | ## External Links - [Official Mednafen Website](https://mednafen.github.io/) - [Official Mednafen Downloads](https://mednafen.github.io/releases/) - [Libretro Beetle SuperGrafx Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mednafen_supergrafx_libretro.info) - [Libretro Beetle SuperGrafx Github Repository](https://github.com/libretro/beetle-supergrafx-libretro) - [Report Libretro Beetle SuperGrafx Core Issues Here](https://github.com/libretro/beetle-supergrafx-libretro/issues) ## TG-16 - [NEC - PC Engine / CD (Beetle PCE FAST)](beetle_pce_fast.md) ================================================ FILE: docs/library/beetle_vb.md ================================================ # Nintendo - Virtual Boy (Beetle VB) ## Background Port of Mednafen VB to libretro. ### Author/License The Beetle VB core has been authored by - [Mednafen Team](https://mednafen.github.io/) The Beetle VB core is licensed under - [GPLv2](https://github.com/libretro/beetle-vb-libretro/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Beetle VB core have the following file extensions: - .vb - .vboy - .bin ## Databases RetroArch database(s) that are associated with the Beetle VB core: - [Nintendo - Virtual Boy](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Virtual%20Boy.rdb) ## Features Frontend-level settings or features that the Beetle VB core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay (State based) | ✔ (not link-cable emulation) | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | Cheats (Cheats menu) | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✔ | | LEDs | ✕ | ### Directories The Beetle VB core's directory name is 'Beetle VB' The Beetle VB core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.srm (Cartridge battery save) **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The Beetle VB core's core provided FPS is 50.27 - The Beetle VB core's core provided sample rate is 44100 Hz - The Beetle VB core's core provided aspect ratio is 12/7 ## Core options The Beetle VB core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Anaglyph preset (restart)** [vb_anaglyph_preset] (**Off**/red & blue/red & cyan/red & electric cyan/red & green/green & magenta/yellow & blue) Select anaglyph 3D mode. !!! attention These Analglyph preset screenshots have been taken with the Palette core option set to black & red. ??? note "Anaglyph preset - Off" ![](../image/core/beetle_vb/off.png) ??? note "Anaglyph preset - red & blue" ![](../image/core/beetle_vb/red&blue.png) ??? note "Anaglyph preset - red & cyan" ![](../image/core/beetle_vb/red&cyan.png) ??? note "Anaglyph preset - red & electric cyan" ![](../image/core/beetle_vb/red&electriccyan.png) ??? note "Anaglyph preset - red & green" ![](../image/core/beetle_vb/red&green.png) ??? note "Anaglyph preset - green & magenta" ![](../image/core/beetle_vb/green&magenta.png) ??? note "Anaglyph preset - yellow & blue" ![](../image/core/beetle_vb/yellow&blue.png) - **Palette (restart)** [vb_color_mode] (**black & red**/black & white) Choose which color palette to use. ??? note "Palette - black & red" ![](../image/core/beetle_vb/black&red.png) ??? note "Palette - black & white" ![](../image/core/beetle_vb/black&white.png) - **Right Analog to Digital** [vb_right_analog_to_digital] (**Off**/On/invert x/invert y/invert both) Self-explanatory. ## Controllers The Beetle VB core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. - **RetroPad** - Joypad - Retropad w/Analog - Joypad - There's no reason to switch to this. ### Controller tables #### Joypad !!! attention The Right D-Pad X and Right D-Pad Y inputs are only active when the 'Right Analog to Digital' core option is set to anything other than Off. | User 1 Remap descriptors | RetroPad Inputs | |--------------------------|----------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | Left D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | Left D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | Left D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | Left D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | | Right D-Pad Up | ![](../image/retropad/retro_l2.png) | | Right D-Pad Left | ![](../image/retropad/retro_r2.png) | | Right D-Pad Down | ![](../image/retropad/retro_l3.png) | | Right D-Pad Right | ![](../image/retropad/retro_r3.png) | | Right D-Pad X | ![](../image/retropad/retro_right_stick.png) X | | Right D-Pad Y | ![](../image/retropad/retro_right_stick.png) Y | ## Compatibility Awaiting description. ## External Links - [Official Mednafen Website](https://mednafen.github.io/) - [Official Mednafen Downloads](https://mednafen.github.io/releases/) - [Official Mednafen Virtual Boy Documentation](https://mednafen.github.io/documentation/vb.html) - [Libretro Beetle VB Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mednafen_vb_libretro.info) - [Libretro Beetle VB Github Repository](https://github.com/libretro/beetle-vb-libretro) - [Report Libretro Beetle VB Core Issues Here](https://github.com/libretro/beetle-vb-libretro/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0Ie8JxLxnW6r6_OeI8TSBPH_) ================================================ FILE: docs/library/bios.md ================================================ ## **Verifying that you have the right BIOS** It is very important that the following requirements are met: 1. Location 2. Name 3. File Hash (md5sum) ### **Location** Ensure that you have placed the BIOS file(s) in the correct location. Usually is the system folder, which can be located in RetroArch by going to: Settings->Directory->System/BIOS (look at the right column). The specific core information page will tell you where exactly. (you may need to create a subfolder) ### **Name** Verify that the file(s) have the same name and extension that appears in the core info/docs page. Remember that some operating systems are case sensitive. ###**File Hash (md5sum)** Last, but probably the most important part of all, the hash of your BIOS should match the one in the docs. #### *What is a hash?* A File Hash is a string of characters that uniquely identifies a file. #### *Why should i care?* If i rename *dog.jpg* to *bios.bin*, how would you know? If the dump is not the version that the core needs, or if the file integrity is compromised (corrupted), unexpected things (**bad**) can happen. A file can become corrupted by errors in transmission, write errors during copying or moving, faulty storage media, software bugs, etc. #### *How do i check it?* You need two things, a piece of software that can generate a hash from your file and a known valid file hash for the comparison, you will find the correct hash in the corresponding core information page (links below) As for the software, some operating systems have tools integrated in the commandline that can do the job, but if you prefer a graphical interface look for something like Open-Hashtool, HashMyFiles, etc ## Links to the core specific BIOS information System | Core | Link | |:----------------------------|:-------------------|:--------------------------------------------------------------------| 3DO | Opera | [BIOS information](opera.md#bios) 5200/Atari 8-bit computers | Atari800 | [BIOS information](atari800.md#bios) 7800 | ProSystem | [BIOS information](prosystem.md#bios) Apple | minivmac | [BIOS information](minivmac.md#bios) Arcade | MAME2003 | [BIOS information](mame_2003.md#bios) Arcade | MAME2003+ | [BIOS information](mame2003_plus.md#bios) Arcade | MAME2010 | [BIOS information](mame_2010.md#bios) Arcade | SAME_CDI | [BIOS information](same_cdi.md#bios) BBK electronic dictionary | GAM4980 | [BIOS information](gam4980.md#bios) ColecoVision | Gearcoleco | [BIOS information](gearcoleco.md#bios) Dreamcast | Flycast | [BIOS information](flycast.md#bios) DS | DeSmuME | [BIOS information](desmume.md#bios) DS | melonDS DS | [BIOS information](melonds_ds.md#bios) Elektronika - BK-0010/BK-0011 | bk | [BIOS information](bk.md#bios) Enterprise 128 | ep128emu | [BIOS information](ep128emu.md#bios) GameBoy/GameBoy Color | Emux GB | [BIOS information](emux_gb.md#bios) GameBoy/GameBoy Color | Gambatte | [BIOS information](gambatte.md#bios) GameBoy/GameBoy Color | Gearboy | [BIOS information](gearboy.md#bios) GameBoy/GameBoy Color | SameBoy | [BIOS information](sameboy.md#bios) GameBoy Advance | Beetle GBA | [BIOS information](beetle_gba.md#bios) GameBoy Advance | gpSP | [BIOS information](gpsp.md#bios) GameBoy Advance | mGBA | [BIOS information](mgba.md#bios) GameBoy Advance | VBA Next | [BIOS information](vba_next.md#bios) Gamecube/Wii | Dolphin | [BIOS information](dolphin.md#bios) Intellivision | FreeIntv | [BIOS information](freeintv.md#bios) Lynx | Beetle Lynx | [BIOS information](beetle_lynx.md#bios) Lynx | Handy | [BIOS information](handy.md#bios) Lynx | Holani | [BIOS information](holani.md#bios) Master System | Emux SMS | [BIOS information](emux_sms.md#bios) MS/GG | SMS Plus GX | [BIOS information](smsplus.md#bios) MS/GG/MD/CD | Genesis Plus GX | [BIOS information](genesis_plus_gx.md#bios) MS/GG/SG-1000 | Gearsystem | [BIOS information](gearsystem.md#bios) MS/MD/CD/32X | PicoDrive | [BIOS information](picodrive.md#bios) MSX/SVI/ColecoVision/SG-1000 | blueMSX | [BIOS information](bluemsx.md#bios) MSX | fMSX | [BIOS information](fmsx.md#bios) NES/Famicom | FCEUmm | [BIOS information](fceumm.md#bios) NES/Famicom | Nestopia | [BIOS information](nestopia.md#bios) NES/Famicom | Mesen | [BIOS information](mesen.md#bios) Odyssey2/Videopac+ | O2EM | [BIOS information](o2em.md#bios) PC-98 | Neko Project II Kai| [BIOS information](neko_project_ii_kai.md#bios) PC Engine/CD | Beetle PCE FAST | [BIOS information](beetle_pce_fast.md#bios) PCE SuperGrafx | Beetle SGX | [BIOS information](beetle_sgx.md#bios) PC-FX | Beetle PC-FX | [BIOS information](beetle_pc_fx.md#bios) PlayStation | Beetle PSX | [BIOS information](beetle_psx.md#bios) PlayStation | Beetle PSX HW | [BIOS information](beetle_psx_hw.md#bios) PlayStation | PCSX ReARMed | [BIOS information](pcsx_rearmed.md#bios) Pokémon Mini | PokeMini | [BIOS information](pokemini.md#bios) PSP | PPSSPP | [BIOS information](ppsspp.md#bios) RPG Maker 2000/2003 | EasyRPG | [BIOS information](easyrpg.md#rtp-files) RPG Maker XP/VX/VX Ace | mkxp-z | [BIOS information](mkxp-z.md#bios) Saturn | Beetle Saturn | [BIOS information](beetle_saturn.md#bios) Saturn | Kronos | [BIOS information](kronos.md#bios) Saturn | Yabause | [BIOS information](yabause.md#bios) Saturn | YabaSanshiro | [BIOS information](yabasanshiro.md#bios) Sharp - X68000 | PX68k | [BIOS information](px68k.md#bios) SNES/Super Famicom | bsnes Accuracy | [BIOS information](bsnes_accuracy.md#bios) SNES/Super Famicom | bsnes Balanced | [BIOS information](bsnes_balanced.md#bios) SNES/Super Famicom | bsnes Performance | [BIOS information](bsnes_performance.md#bios) SNES/Super Famicom | bsnes-mercury Acc | [BIOS information](bsnes_mercury_accuracy.md#bios) SNES/Super Famicom | bsnes-mercury Bal | [BIOS information](bsnes_mercury_balanced.md#bios) SNES/Super Famicom | bsnes-mercury Perf | [BIOS information](bsnes_mercury_performance.md#bios) SNES/Super Famicom | nSide Balanced | [BIOS information](nside_balanced.md#bios) SNES/Super Famicom | higan Accuracy | [BIOS information](higan_accuracy.md#bios) SNES/Super Famicom | Mesen-S | [BIOS information](mesen-s.md#bios) Super Cassette Vision | EmuSCV | [BIOS information](emuscv.md#bios) ST/STE/TT/Falcon | Hatari | [BIOS information](hatari.md#bios) Texas Instruments TI-83 | Numero | [BIOS information](numero.md#bios) Thomson - MO/TO | Theodore | [BIOS information](theodore.md#bios) Vectrex | vecx | [BIOS information](vecx.md#bios) Vircon32 | Vircon32 | [BIOS information](vircon32.md#bios) ZX Spectrum | Fuse | [BIOS information](fuse.md#bios) ================================================ FILE: docs/library/bk.md ================================================ # Elektronika - BK-0010/BK-0011(M) (bk) ## Background A port of the PDP11 emulator to libretro. This core emulates the Soviet Electronica BK computers series, including the BK-0010, BK-0010.01 and BK-0011(M), as well as the Terak 8510/a, which is a 1976 American PDP-11/03 platform that the Electronica BK series were designed after. The BK series computers were the first mass-produced, affordable personal computers in Russia in the 1980s and they had a tremendous effect on the development of the Russian-speaking software community, similar to the C64, ZX Spectrum and Atari 2600 communities elsewhere in the world. These computers will accept console commands in English but respond mostly in Russian, so this core is mostly of use to Russian-speaking users. This is a core for Soviet (russian) Electronica BK series: - БК-0010 - БК-0010.01 - БК-0011(М) You may read more about the series at http://en.wikipedia.org/wiki/Electronika_BK The author's (Leonid A. Broukhis) page can be found at [here](http://www.mailcom.com/bk0010/index_en.shtml). Additionally, it supports emulation of Terak 8510/a, which is a 1976 american PDP-11/03 platform and of which the Electronica BK series are indeed clones. The Electronica BK computers were the first mass produced, affordable personal computers in Russia in the eighties of 20th century, and have had tremendous effect on the development of Russian-speaking software community. Every russian computer, hardware or ham radio geek born in seventies or eighties probably had one of those machines during their formational years. They are the C64s, ZX Spectrums and Atari 2600s of the now defunct USSR. All of the BK machines accept console commands in English, but respond mostly in Russian. Virtually all of BK schematics, documentation, hardware hacks and software has been preserved and is available on the internet. Unfortunately, most if not all of these things are only available in Russian. ### Author/License The bk core has been authored by - Eric A. Edwards - Leonid A. Broukhis - emestee - arcade-mini - phcoder The bk core is licensed under - [BSD](https://github.com/libretro/bk-emulator/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the bk core have the following file extensions: - .bin ## Databases *WIP* RetroArch database(s) that are associated with the bk core: ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:---------------:|:----------------------:|:--------------------------------:| | bk/B11M_BOS.ROM | | fe4627d1e3a1535874085050733263e7 | | bk/B11M_EXT.ROM | | dc52f365d56fa1951f5d35b1101b9e3f | | bk/BAS11M_0.ROM | | 946f6f23ded03c0e26187f0b3ca75993 | | bk/BAS11M_1.ROM | | 1e6637f32aa7d1de03510030cac40bcf | | bk/DISK_327.ROM | | 5015228eeeb238e65da8edcd1b6dfac7 | | bk/BASIC10.ROM | | 3fa774326d75410a065659aea80252f0 | | bk/FOCAL10.ROM | | 5737f972e8638831ab71e9139abae052 | | bk/MONIT10.ROM | | 95f8c41c6abf7640e35a6a03cecebd01 | ## Features Frontend-level settings or features that the bk core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✕ | | Screenshots | ✔ | | Saves | ✕ | | States | ✕ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The bk core's library name is 'bk' The bk core saves/loads to/from these directories. ### Geometry and timing - The bk core's core provided FPS is 25. - The bk core's core provided sample rate is 44100 Hz. - The bk core's base width is 1080. - The bk core's base height is 1080. - The bk core's core provided aspect ratio is 1/1. ## Core options The bk core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Model (restart)** [bk_model] (**BK-0010**|BK-0010.01|BK-0010.01 + FDD|BK-0011M + FDD|Terak 8510/a|Slow BK-0011M) - **Peripheral (UP port, restart)** [bk_peripheral] (**none**|covox|ay_3_8910|mouse_high|mouse_low|joystick) - **Keyboard layout** [bk_layout] (**qwerty**|jcuken) - **Double CPU speed** [bk_doublespeed] (**disabled**|enabled) - **Use color display** [bk_color] (**enabled**|disabled) - **Keyboard type (restart)** [bk_keyboard_type] (**poll**|callback) - **Aspect ratio** [bk_aspect_ratio] (**1:1**|4:3) ## Controllers The bk core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. There's no reason to switch to this. - **Joystick** - Joypad - RetroKeyboard - Keyboard - Keyboard inputs are always active. Has keymapper support. - RetroPad Keyboard Map - Joypad - Awaiting description. ### Controller tables #### Keyboard | RetroKeyboard Inputs | RetroKeyboard | |------------------------------|-----------------------| | Keyboard Backspace | BACKSPACE | | Keyboard Tab | TAB | | Keyboard Return | RETURN | | Keyboard Pause | PAUSE | | Keyboard Escape | ESCAPE | | Keyboard Space | SPACE | | Keyboard Quote ' | COLON | | Keyboard Comma , | COMMA | | Keyboard Minus - | NEGATIVE | | Keyboard Period . | PERIOD | | Keyboard Slash / | DIVIDE | | Keyboard 0 | 0 | | Keyboard 1 | 1, Player 1 Coleco #0 | | Keyboard 2 | 2, Player 1 Coleco #9 | | Keyboard 3 | 3, Player 2 Coleco #0 | | Keyboard 4 | 4, Player 2 Coleco #9 | | Keyboard 5 | 5 | | Keyboard 6 | 6 | | Keyboard 7 | 7 | | Keyboard 8 | 8 | | Keyboard 9 | 9 | | Keyboard Semicolon ; | SEMICOLON | | Keyboard Equals = | CIRCUMFLEX | | Keyboard Left Bracket [ | LEFT BRACKET | | Keyboard Backslash \ | BACKSLASH (YEN) | | Keyboard Right Bracket ] | RIGHT BRACKET | | Keyboard Backquote ` | AT | | Keyboard a | A | | Keyboard b | B | | Keyboard c | C | | Keyboard d | D | | Keyboard e | E | | Keyboard f | F | | Keyboard g | G | | Keyboard h | H | | Keyboard i | I | | Keyboard j | J | | Keyboard k | K | | Keyboard l | L | | Keyboard m | M | | Keyboard n | N | | Keyboard o | O | | Keyboard p | P | | Keyboard q | Q | | Keyboard r | R | | Keyboard s | S | | Keyboard t | T | | Keyboard u | U | | Keyboard v | V | | Keyboard w | W | | Keyboard x | X | | Keyboard y | Y | | Keyboard z | Z | | Keyboard Delete | DELETE | | Keyboard Keypad 0 | NUMPAD 0 | | Keyboard Keypad 1 | NUMPAD 1 | | Keyboard Keypad 2 | NUMPAD 2 | | Keyboard Keypad 3 | NUMPAD 3 | | Keyboard Keypad 4 | NUMPAD 4 | | Keyboard Keypad 5 | NUMPAD 5 | | Keyboard Keypad 6 | NUMPAD 6 | | Keyboard Keypad 7 | NUMPAD 7 | | Keyboard Keypad 8 | NUMPAD 8 | | Keyboard Keypad 9 | NUMPAD 9 | | Keyboard Keypad Period . | NUMPAD COMMA | | Keyboard Keypad Divide / | NUMPAD DIVIDE | | Keyboard Keypad Multiply * | NUMPAD MULTIPLY | | Keyboard Keypad Minus - | NUMPAD SUBTRACTION | | Keyboard Keypad Plus + | NUMPAD ADD | | Keyboard Keypad Enter | NUMPAD PERIOD | | Keyboard Up | UP | | Keyboard Down | DOWN | | Keyboard Right | RIGHT | | Keyboard Left | LEFT | | Keyboard Insert | INSERT | | Keyboard Home | CLS | | Keyboard End | STOP | | Keyboard Page Up | SELECT | | Keyboard F1 | F1 | | Keyboard F2 | F2 | | Keyboard F3 | F3 | | Keyboard F4 | F4 | | Keyboard F5 | F5 | | Keyboard Caps Lock | CAPS | | Keyboard Right Shift | RIGHT SHIFT | | Keyboard Left Shift | LEFT SHIFT | | Keyboard Left Control | CONTROL | | Keyboard Left Alt | GRAPH | | Keyboard Print | PRINT | Supported combinations ## External Links - [Official bk Website](http://www.mailcom.com/bk0010/index_en.shtml) - [bk Repository](https://github.com/emestee/bk-emulator) - [Libretro bk Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/bk_libretro.info) - [Libretro bk Github Repository](https://github.com/libretro/bk-emulator) - [Report Libretro bk Core Issues Here](https://github.com/libretro/bk-emulator/issues) ================================================ FILE: docs/library/blastem.md ================================================ # Sega - MD/CD (BlastEm) ## Background BlastEm is an open-source Sega 16 bit emulator focused on accuracy and portability. BlastEm has 100% compatibility with Genesis / Mega Drive. The BlastEm core is licensed under A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:----------------------------------------------------------------------------:|:-------------------------------:|:----------:| | [rom.db](https://raw.githubusercontent.com/libretro/blastem/libretro/rom.db) | ROM feature database - Optional | | ## External Links ================================================ FILE: docs/library/bluemsx.md ================================================ # MSX/SVI/ColecoVision/SG-1000 (blueMSX) ## Background blueMSX is a cycle accurate emulator that emulates all generations of MSX computers as well as SVI, ColecoVision and Sega SG-1000. ### Author/License The blueMSX core has been authored by - Daniel Vik The blueMSX core is licensed under - [GPLv2](https://github.com/libretro/blueMSX-libretro/blob/master/license.txt) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the blueMSX core have the following file extensions: - .rom - .ri - .mx1 - .mx2 - .col - .dsk - .cas - .sg - .sc - .m3u ## Databases RetroArch database(s) that are associated with the blueMSX core: - [Microsoft - MSX](https://github.com/libretro/libretro-database/blob/master/rdb/Microsoft%20-%20MSX.rdb) - [Microsoft - MSX2](https://github.com/libretro/libretro-database/blob/master/rdb/Microsoft%20-%20MSX2.rdb) - [Coleco - ColecoVision](https://github.com/libretro/libretro-database/blob/master/rdb/Coleco%20-%20ColecoVision.rdb) - [Sega - SG-1000](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20SG-1000.rdb) ## BIOS The blueMSX core requires the 'Databases' and 'Machines' folders from a full installation of blueMSX. Go to `Main Menu > Online Updater > Core System Files Downloader` and download 'blueMSX.zip'. That's all you need to do! The 'Databases' and 'Machines' folders will be extracted and moved to your RetroArch 'system' folder automatically. Alternatively, if your frontend doesn't have the 'Core System Files Downloader': You can download the 'Databases' and 'Machines' folders from an [official full standalone blueMSX emulator installation](http://bluemsx.msxblue.com/download.html). Get blueMSXv282full.zip near the bottom of the page. Move/Copy the 'Databases' and 'Machines' Folders to RetroArch's System directory. ![](../image/core/bluemsx/bios.png) ## Features Frontend-level settings or features that the blueMSX core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✕ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✔ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The blueMSX core's library name is 'blueMSX' The blueMSX core saves/loads to/from these directories. **Frontend's System directory** | File | Description | |:-------------------:|:---------------:| | bluemsx.ini | blueMSX Config | | bluemsx_history.ini | blueMSX History | ### Geometry and timing - The blueMSX core's core provided FPS is 60 - The blueMSX core's core provided sample rate is 44100 Hz - The blueMSX core's base width is (Base width) - The blueMSX core's base height is (Base height) - The blueMSX core's max width is (Max width) - The blueMSX core's max height is (Max height) - The blueMSX core's core provided aspect ratio is (Ratio) ## Usage ColecoVision Gamepad Mapping is as follow: - Button 1 as Retropad A - Button 2 as Retropad B - Dial keys 1 to 8 as X, Y, R, L, R2, L2, R3, L3 - Star (*) as Select, Hash (#) as Start - 0 & 9 are on keyboard 1 & 2 for Player 1 - 0 & 9 are on keyboard 3 & 4 for Player 2. ## SpectraVideo Cassettes To play SpectraVideo cassettes type 'cload' then 'run' or BLOAD ''CAS:'',R depending on the game. ## Multiple-disk games If foo is a multiple-disk game, you should have .dsk files for each one, e.g. `foo (Disk 1).dsk`, `foo (Disk 2).dsk`, `foo (Disk 3).dsk`. To take advantage of BlueMSX Disk Control feature for disk swapping, an index file (a m3u file) should be made. Create a text file and save it as `foo.m3u`. Then enter your game's .dsk files on it. The m3u file contents should look something like this: `foo.m3u` ``` foo (Disk 1).dsk foo (Disk 2).dsk foo (Disk 3).dsk ``` After that, you can load the `foo.m3u` file in RetroArch with the BlueMSX core. An alternative is to append disks to the current playlist via the "Disk Image Append" option RetroArch menu. ## Core options The blueMSX core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Machine Type (Restart)** [bluemsx_msxtype] (**Auto**|MSX|MSXturboR|MSX2|MSX2+|SEGA - SG-1000|SEGA - SC-3000|SEGA - SF-7000|SVI - Spectravideo SVI-318|SVI - Spectravideo SVI-328|SVI - Spectravideo SVI-328 MK2|ColecoVision|Coleco (Spectravideo SVI-603)) Manually select the machine type you would like the core to start in. - **Crop Overscan** [bluemsx_overscan] (**disabled**|enabled|MSX2) Forces cropping of overscanned frames ??? note "*Crop Overscan Off*" ![](../image/core/bluemsx/crop_off.png) ??? note "*Crop Overscan On*" ![](../image/core/bluemsx/crop_on.png) ??? note "*Crop Overscan MSX2*" ![](../image/core/bluemsx/crop_msx2.png) - **VDP Sync Type (Restart)** [bluemsx_vdp_synctype] (**Auto**|50Hz|60Hz) Match the game/machine region frequency to avoid emulated speed issues. - **No Sprite Limit** [bluemsx_nospritelimits] (**OFF**|ON) Remove the 4 sprite per line limit which can reduce or remove sprite flicker in some games. - **Sound YM2413 Enable (Restart)** [bluemsx_ym2413_enable] (**enabled**|disabled) Awaiting description. - **Cart Mapper Type (Restart)** [bluemsx_cartmapper] (**Auto**|Normal|mirrored|basic|0x4000|0xC000|ascii8|ascii8sram|ascii16|ascii16sram| ascii16nf|konami4|konami4nf|konami5|konamisynth|korean80|korean90|korean126| MegaFlashRomScc|MegaFlashRomSccPlus|msxdos2|scc|sccexpanded|sccmirrored|sccplus| snatcher|sdsnatcher|SegaBasic|SG1000|SG1000Castle|SG1000RamA|SG1000RamB|SC3000) When a ROM game or application is in the database, the emulator uses the databases to apply the correct mapper. If the sha1 value of a dump is not yet in the databases, it uses an automatic mapper detection system, but it can fail in some cases. In this situation, you can manually select the correct mapper. ## Controllers The blueMSX core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. There's no reason to switch to this. - **RetroPad** - Joypad - RetroKeyboard - Keyboard - Keyboard inputs are always active. Has keymapper support. - RetroPad Keyboard Map - Joypad - Awaiting description. ### User 2 device types - None - Doesn't disable input. There's no reason to switch to this. - **RetroPad** - Joypad - RetroKeyboard - Keyboard - Keyboard inputs are always active. ### Controller tables #### Joypad | User 1 and 2 Remap descriptors for 'RetroPad' device type | RetroPad Inputs | blueMSX core inputs | |-----------------------------------------------------------|------------------------------------------------|----------------------------| | Button 2 | ![](../image/retropad/retro_b.png) | Button 2, Coleco Button 2 | | Button 3 | ![](../image/retropad/retro_y.png) | Button 3, Coleco #2 | | Select | ![](../image/retropad/retro_select.png) | Select, Coleco Star (*) | | Start | ![](../image/retropad/retro_start.png) | Start, Coleco Hash (#) | | Joy Up | ![](../image/retropad/retro_dpad_up.png) | Joy Up | | Joy Down | ![](../image/retropad/retro_dpad_down.png) | Joy Down | | Joy Left | ![](../image/retropad/retro_dpad_left.png) | Joy Left | | Joy Right | ![](../image/retropad/retro_dpad_right.png) | Joy Right | | Button 1 | ![](../image/retropad/retro_a.png) | Button 1, Coleco Button 1 | | Button 4 | ![](../image/retropad/retro_x.png) | Button 4, Coleco #1 | | Button 5 | ![](../image/retropad/retro_l1.png) | Button 5, Coleco #4 | | Button 6 | ![](../image/retropad/retro_r1.png) | Button 6, Coleco #3 | | Button 7 | ![](../image/retropad/retro_l2.png) | Button 7, Coleco #6 | | Button 8 | ![](../image/retropad/retro_r2.png) | Button 8, Coleco #5 | | Button 9 | ![](../image/retropad/retro_l3.png) | Button 9. Coleco #8 | | Button 10 | ![](../image/retropad/retro_r3.png) | Button 10, Coleco #7 | #### Keyboard | RetroKeyboard Inputs | RetroKeyboard | |------------------------------|-----------------------| | Keyboard Backspace | BACKSPACE | | Keyboard Tab | TAB | | Keyboard Return | RETURN | | Keyboard Pause | PAUSE | | Keyboard Escape | ESCAPE | | Keyboard Space | SPACE | | Keyboard Quote ' | COLON | | Keyboard Comma , | COMMA | | Keyboard Minus - | NEGATIVE | | Keyboard Period . | PERIOD | | Keyboard Slash / | DIVIDE | | Keyboard 0 | 0 | | Keyboard 1 | 1, Player 1 Coleco #0 | | Keyboard 2 | 2, Player 1 Coleco #9 | | Keyboard 3 | 3, Player 2 Coleco #0 | | Keyboard 4 | 4, Player 2 Coleco #9 | | Keyboard 5 | 5 | | Keyboard 6 | 6 | | Keyboard 7 | 7 | | Keyboard 8 | 8 | | Keyboard 9 | 9 | | Keyboard Semicolon ; | SEMICOLON | | Keyboard Equals = | CIRCUMFLEX | | Keyboard Left Bracket [ | LEFT BRACKET | | Keyboard Backslash \ | BACKSLASH (YEN) | | Keyboard Right Bracket ] | RIGHT BRACKET | | Keyboard Backquote ` | AT | | Keyboard a | A | | Keyboard b | B | | Keyboard c | C | | Keyboard d | D | | Keyboard e | E | | Keyboard f | F | | Keyboard g | G | | Keyboard h | H | | Keyboard i | I | | Keyboard j | J | | Keyboard k | K | | Keyboard l | L | | Keyboard m | M | | Keyboard n | N | | Keyboard o | O | | Keyboard p | P | | Keyboard q | Q | | Keyboard r | R | | Keyboard s | S | | Keyboard t | T | | Keyboard u | U | | Keyboard v | V | | Keyboard w | W | | Keyboard x | X | | Keyboard y | Y | | Keyboard z | Z | | Keyboard Delete | DELETE | | Keyboard Keypad 0 | NUMPAD 0 | | Keyboard Keypad 1 | NUMPAD 1 | | Keyboard Keypad 2 | NUMPAD 2 | | Keyboard Keypad 3 | NUMPAD 3 | | Keyboard Keypad 4 | NUMPAD 4 | | Keyboard Keypad 5 | NUMPAD 5 | | Keyboard Keypad 6 | NUMPAD 6 | | Keyboard Keypad 7 | NUMPAD 7 | | Keyboard Keypad 8 | NUMPAD 8 | | Keyboard Keypad 9 | NUMPAD 9 | | Keyboard Keypad Period . | NUMPAD COMMA | | Keyboard Keypad Divide / | NUMPAD DIVIDE | | Keyboard Keypad Multiply * | NUMPAD MULTIPLY | | Keyboard Keypad Minus - | NUMPAD SUBTRACTION | | Keyboard Keypad Plus + | NUMPAD ADD | | Keyboard Keypad Enter | NUMPAD PERIOD | | Keyboard Up | UP | | Keyboard Down | DOWN | | Keyboard Right | RIGHT | | Keyboard Left | LEFT | | Keyboard Insert | INSERT | | Keyboard Home | CLS | | Keyboard End | STOP | | Keyboard Page Up | SELECT | | Keyboard F1 | F1 | | Keyboard F2 | F2 | | Keyboard F3 | F3 | | Keyboard F4 | F4 | | Keyboard F5 | F5 | | Keyboard Caps Lock | CAPS | | Keyboard Right Shift | RIGHT SHIFT | | Keyboard Left Shift | LEFT SHIFT | | Keyboard Left Control | CONTROL | | Keyboard Left Alt | GRAPH | | Keyboard Print | PRINT | Supported combinations - Keyboard Left or Right Shift + Keyboard 0 = UNDERSCORE ## Compatibility - [blueMSX Manual](http://www.msxblue.com/manual/settingsports.htm) ## External Links - [Official blueMSX Website](http://bluemsx.com/) - [Official blueMSX SourceForge Repository](http://sourceforge.net/projects/bluemsx/) - [Libretro blueMSX Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/bluemsx_libretro.info) - [Libretro blueMSX Github Repository](https://github.com/libretro/blueMSX-libretro) - [Report Libretro blueMSX Core Issues Here](https://github.com/libretro/blueMSX-libretro/issues) ### See also #### Sega - SG-1000 - [Sega - MS/GG/MD/CD (Genesis Plus GX)](genesis_plus_gx.md) - [Sega - MS/GG/SG-1000 (Gearsystem)](gearsystem.md) #### Microsoft - MSX - [Microsoft - MSX (fMSX)](fmsx.md) #### Microsoft - MSX2 - [Microsoft - MSX (fMSX)](fmsx.md) #### ColecoVision - [Coleco - ColecoVision (Gearcoleco)](gearcoleco.md) - [ColecoVision/CreatiVision/My Vision (JollyCV)](jollycv.md) ================================================ FILE: docs/library/bnes.md ================================================ # Nintendo - NES / Famicom (bnes) ## Background A port of bNES v083 to libretro. ### Author/License The bnes core has been authored by - byuu - Ryphecha The bnes core is licensed under - [GPLv3](https://github.com/libretro/bnes-libretro/blob/master/license) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the bnes core have the following file extensions: - .nes ## Databases RetroArch database(s) that are associated with the bnes core: - [Nintendo - Nintendo Entertainment System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%20Entertainment%20System.rdb) ## Features Frontend-level settings or features that the bnes core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The bnes core's directory name is 'bnes' The bnes core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.srm (Cartridge battery save) **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The bnes core's core provided FPS is 60 - The bnes core's core provided sample rate is 32000 Hz - The bnes core's core provided aspect ratio is 16/15 ## Controllers The bnes core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 - 2 device types - None - Doesn't disable input. - **RetroPad** - Joypad - RetroPad w/Analog - Joypad - There is no reason to switch to this. ### Controller tables #### Joypad ![](../image/controller/nes.png) | User 1 - 2 Remap descriptors | RetroPad Inputs | |------------------------------|-------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | ## Compatibility | Game | Issue | |------------------------------|------------------------------------------------| | Crisis Force | Graphical glitches. (1) | | Huge Insect | No enemies spawn. | | Lagrange Point | No music. | | Ms. Pac-Man (Tengen version) | Graphical glitches on the sides of the screen. | | Skull & Crossbones | Crashes on start. | ??? note "(1)" ![](../image/core/bnes/crisisforce.png) ## External Links - [Official higan Website](https://byuu.org/) - [Official higan Downloads](https://byuu.org/emulation/higan/) - [Libretro bnes Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/bnes_libretro.info) - [Libretro bnes Github Repository](https://github.com/libretro/bnes-libretro) - [Report Libretro bnes Core Issues Here](https://github.com/libretro/bnes-libretro/issues) ### See also #### Nintendo - Nintendo Entertainment System - [Nintendo - NES / Famicom (Emux NES)](emux_nes.md) - [Nintendo - NES / Famicom (FCEUmm)](fceumm.md) - [Nintendo - NES / Famicom (Mesen)](mesen.md) - [Nintendo - NES / Famicom (Nestopia)](nestopia.md) - [Nintendo - NES / Famicom (QuickNES)](quicknes.md) ================================================ FILE: docs/library/boom3.md ================================================ # Doom 3 (Boom3) ## Background Boom 3[^1] is a Doom 3 and Doom 3: Resurrection Of Evil GPL source port, known to work on Windows and Linux. Doom 3 is a sci-fi horror fantasy first-person shooter computer game developed by id Software and published by ActiVision. The PrBoom core has been authored by - The Boom 3 core is licensed under - [GPLv3](https://github.com/libretro/boom3/blob/master/COPYING.txt) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS There are no required BIOS. ## Extensions Content that can be loaded by the Boom 3 core have the following file extensions: - .pk4 RetroArch database(s) that are associated with the PrBoom core: - [DOOM](https://github.com/libretro/libretro-database/blob/master/rdb/DOOM.rdb) ## Features Frontend-level settings or features that the PrBoom core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✕ | | Screenshots | ✔ | | Saves | ✔ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✔ | | Native Cheats | ✔ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Boom 3 core's library name is 'boom3' The Boom 3 core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-------------------------:|:-----------:| | (conten folder)/savegames/*.save | Save | | (content folder)/libretro.cfg | DOOM 3 Config | ### Geometry and timing - The Boom 3 core's core provided FPS (by default) is 60 - The Boom 3 core's core provided sample rate is 44100 Hz - The Boom 3 core's base width is dependent on the Internal resolution core option. - The Boom 3 core's base height is dependent on the Internal resolution core option. - The Boom 3 core's max width is dependent on the Internal resolution core option. - The Boom 3 core's max height is dependent on the Internal resolution core option. - The Boom 3 core's core provided aspect ratio is 4/3 ## Loading DOOM 3 files Boom 3 can load pk4 files. The Boom 3 core requires game data files which can be found [here](https://store.steampowered.com/app/9050/DOOM_3/) and [here](https://store.steampowered.com/app/9070/). If you bought the game on CDs/DVD, base/pak000.pk4 - pak004.pk4 and d3xp/pak000.pk4 can be copied from the disks, the other files are from the patch. On Linux (and probably other Unix-like systems and maybe even Windows with a mingw shell) you can extract the needed files from [the official 1.3.1 patch for Linux with](https://files.holarse-linuxgaming.de/native/Spiele/Doom%203/doom3-linux-1.3.1.1304.x86.run): ```sh sh /path/to/doom3-linux-1.3.1.1304.x86.run --tar xvf --wildcards base/pak* d3xp/pak* ``` On Windows you can just install the game and [the official 1.3.1 patch for Windows](https://archive.org/details/Doom_3_1.3.1) and then get the files from the installation directory (or copy dhewm3 in there). !!! WARNING Doom3 BFG is not supported. You'll need the game data from a Doom3 installation patched to 1.3.1. Specifically, you'll need the following .pk4 files for the main game: ``` Filename Size MD5-sum base/pak000.pk4 337MB 71b8d37b2444d3d86a36fd61783844fe base/pak001.pk4 220MB 4bc4f3ba04ec2b4f4837be40e840a3c1 base/pak002.pk4 398MB fa84069e9642ad9aa4b49624150cc345 base/pak003.pk4 303MB f22d8464997924e4913e467e7d62d5fe base/pak004.pk4 227MB 38561a3c73f93f2e6fd31abf1d4e9102 base/pak005.pk4 540KB 2afd4ece27d36393b7538d55a345b90d base/pak006.pk4 214KB a6e7003fa9dcc75073dc02b56399b370 base/pak007.pk4 118KB 6319f086f930ec1618ab09b4c20c268c base/pak008.pk4 12KB 28750b7841de9453eb335bad6841a2a5 ``` ... and (optionally) these .pk4 files for the Resurrection of Evil addon: ``` Filename Size MD5-sum d3xp/pak000.pk4 514MB a883fef0fd10aadeb73d34c462ff865d d3xp/pak001.pk4 98KB 06fc9be965e345587064056bf22236d2 ``` An example folder structure would be like so: ``` └── contents/ └── doom3/ ├── base/ │ ├── pak000.pk4 │ ├── pak001.pk4 │ ├── pak002.pk4 │ ├── pak003.pk4 │ ├── pak004.pk4 │ ├── pak005.pk4 │ ├── pak006.pk4 │ ├── pak007.pk4 │ └── pak008.pk4 └── d3xp/ ├── pak000.pk4 └── pak001.pk4 ``` Game saves and internal configuration files will be created in the content directory, organised in folders matching the filenames of loaded content - for example: ``` └── contents/ └── doom3/ └── base/ ├── savegames/ │ ├── *.save └── └── *.txt ``` Game saves are named from mission names. ## Loading Doom 3: Resurrection Of Evil Doom 3: Resurrection of Evil is a horror first-person shooter video game developed by Nerve Software and published by Activision. It was released for Microsoft Windows on April 3, 2005, as an expansion pack and sequel to Doom 3 and on October 5, 2005, for the Xbox video game console. The Xbox version does not require the original Doom 3 in order to play, and includes The Ultimate Doom, Doom II: Hell on Earth and Master Levels for Doom II. You will need to get Doom 3 and expansion pack RoE [here](https://store.steampowered.com/app/9070/). You need to load Boom 3 xp core instead of Boom3 core. After Core is loaded you can load RoE's pk4 file ``` └── contents/ └── doom3/ └── d3xp/ ├── pak000.pk4 └── pak001.pk4 ``` You can get Boom 3 xp core [here](https://github.com/fpscan/RetroArch-AppImage/releases/download/A-cores/boom3_xp_libretro.zip) for now. ## Config Boom 3's internal game settings can be found in the 'libretro.cfg' file inside each game's directory. Many of these settings may be changed from the in-game menu. ## Core options The Boom 3 core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Framerate (restart)** [boom3-framerate] (**Auto**|50fps|60fps|72fps|75fps|90fps|100fps|119fps|120fps|144fps|155fps|160fps|165fps|180fps|200fps|240fps|244fps|300fps|360fps) Modify framerate. Requires a restart. ??? note "Internal resolution - 640x368" ![](../image/core/boom3/640x368.png) ??? note "Internal resolution - 1920x1080" ![](../image/core/boom3/1920x1080.png) - **Internal Resolution (restart)** [boom3-resolution] (480x272|**640x368**|720x408|960x544|1280x720|1920x1080|2560x1440|3840x2160) Configure the resolution. Requires a restart. - **Invert Y Axis** [boom3-invert_y_axis] (**OFF**|ON) Invert the gamepad right analog stick's Y axis. - **Show FPS** [boom3-show_fps] (**OFF**|ON) Shows framerate on screen. ## User 1 device types The Boom3 core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): - None - Input disabled. - **Gamepad Classic** - Joypad - **Gamepad Classic Alt** - Joypad - **Gamepad Modern** - Joypad ## Joypad | User 1 input descriptors for 'Gamepad Classic' device type | RetroPad Inputs | PrBoom inputs | |------------------------------------------------------------|---------------------------------------------|-----------------| | Use | ![](../image/retropad/retro_b.png) | Use | | Run | ![](../image/retropad/retro_y.png) | Run | | Show/Hide Map | ![](../image/retropad/retro_select.png) | Show/Hide Map | | Show/Hide Menu | ![](../image/retropad/retro_start.png) | Show/Hide Menu | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | | Fire | ![](../image/retropad/retro_a.png) | Fire | | Strafe | ![](../image/retropad/retro_x.png) | Strafe | | Strafe Left | ![](../image/retropad/retro_l1.png) | Strafe Left | | Strafe Right | ![](../image/retropad/retro_r1.png) | Strafe Right | | Previous Weapon | ![](../image/retropad/retro_l2.png) | Previous Weapon | | Next Weapon | ![](../image/retropad/retro_r2.png) | Next Weapon | | User 1 input descriptors for 'Gamepad Modern' device type | RetroPad Inputs | PrBoom inputs | |-----------------------------------------------------------|------------------------------------------------|-------------------------| | Menu Cancel | ![](../image/retropad/retro_b.png) | Menu Cancel | | Quick Save | ![](../image/retropad/retro_y.png) | Quick Save | | Show/Hide Map | ![](../image/retropad/retro_select.png) | Show/Hide Map | | Show/Hide Menu | ![](../image/retropad/retro_start.png) | Show/Hide Menu | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | | Menu Select | ![](../image/retropad/retro_a.png) | Menu Select | | Quick Load | ![](../image/retropad/retro_x.png) | Quick Load | | Previous Weapon | ![](../image/retropad/retro_l1.png) | Previous Weapon | | Next Weapon | ![](../image/retropad/retro_r1.png) | Next Weapon | | Use | ![](../image/retropad/retro_l2.png) | Use | | Fire | ![](../image/retropad/retro_r2.png) | Fire | | Toggle Run | ![](../image/retropad/retro_l3.png) | Toggle Run | | 180 Turn | ![](../image/retropad/retro_r3.png) | 180 Turn | | | ![](../image/retropad/retro_left_stick.png) X | Strafe Left/Right | | | ![](../image/retropad/retro_left_stick.png) Y | Move Forwards/Backwards | | | ![](../image/retropad/retro_right_stick.png) X | Look Left/Right | ## External Links - [Official dhewm3 Website](https://dhewm3.org/) - [Official dhewm3 Repository](https://github.com/dhewm/dhewm3) - [Libretro Boom 3 Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/boom3_libretro.info) - [Libretro Boom 3 xp Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/boom3_xp_libretro.info) - [Libretro Boom 3 Github Repository](https://github.com/libretro/boom3) - [Report Libretro Boom 3 Core Issues Here](https://github.com/libretro/boom3/issues) ## id Software - [Doom 1&2 (PrBoom)](prboom.md) [^1]: Core renamed to Boom 3 from Dhewm3 [based on original author request.](https://github.com/dhewm/dhewm3/issues/270#issuecomment-573478406) ================================================ FILE: docs/library/bsnes-jg.md ================================================ # Nintendo - SNES / Famicom (bsnes-jg) ## Background bsnes-jg is a cycle accurate emulator for the Super Famicom/Super Nintendo Entertainment System, including support for the Super Game Boy, BS-X Satellaview, and Sufami Turbo. This is a fork of bsnes v115. Many changes have been made post-fork: - Higher quality resampler with settings - Improved performance without loss of accuracy - Portability improvements - Removal of accuracy-reducing hacks and unnecessary code - Significant increase in standards compliance - Translation to the C++ Standard Library (ISO C++11) ### Author/License The bsnes-jg core has been authored by - byuu - [Rupert Carmichael (carmiker)](https://github.com/carmiker) The bsnes-jg core is licensed under - [GPLv3](https://github.com/libretro/bsnes-jg/blob/libretro/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the bsnes-jg core have the following file extensions: - .sfc - .smc - .gb - .gbc - .st - .bs ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:-----------------:|:--------------------------------------:|:--------------------------------:| | dsp1.data.rom | DSP1 co-processor firmware | 3d81b45fa0c2aa8b852dfb1ece7c0971 | | dsp1.program.rom | DSP1 co-processor firmware | ae209fbe789fbf11a48aea5ab1197321 | | dsp1b.data.rom | DSP1B co-processor firmware | 1e3f568634a7d8284020dddc0ae905bc | | dsp1b.program.rom | DSP1B co-processor firmware | d10f446888e097cbf500f3f663cf4f6d | | dsp2.data.rom | DSP2 co-processor firmware | e9417e29223b139c3c4b635a2a3b8744 | | dsp2.program.rom | DSP2 co-processor firmware | aa6e5922a3ed5ded54f24247c11143c5 | | dsp3.data.rom | DSP3 co-processor firmware | 0a81210c0a940b997dd9843281008ee6 | | dsp3.program.rom | DSP3 co-processor firmware | d99ca4562818d49cee1f242705bba6f8 | | dsp4.data.rom | DSP4 co-processor firmware | ee4990879eb68e3cbca239c5bc20303d | | dsp4.program.rom | DSP4 co-processor firmware | a151023b948b90ffc23a5b594bb6fef2 | | cx4.data.rom | CX4 co-processor firmware | 037ac4296b6b6a5c47c440188d3c72e3 | | st010.data.rom | ST010 co-processor firmware | 254d70762b6f59f99c27c395aba7d07d | | st010.program.rom | ST010 co-processor firmware | 1d70019179a59a566a0bb5d3f2845544 | | st011.data.rom | ST011 co-processor firmware | 10bd3f4aa949737ab9836512c35bcc29 | | st011.program.rom | ST011 co-processor firmware | 95222ebf1c0c2990bcf25db43743f032 | | st018.data.rom | ST018 co-processor firmware | 49c898b60d0f15e90d0ba780dd12f366 | | st018.program.rom | ST018 co-processor firmware | dda40ccd57390c96e49d30a041f9a9e7 | ## Features Frontend-level settings or features that the bsnes-jg core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✔ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✔ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✔ | | LEDs | ✕ | ### Directories The bsnes-jg core's library name is 'bsnes-jg' The bsnes-jg core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:-----------------------------:| | *.srm | Cartridge-based battery saves | | *.rtc | Real Time Clock data | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ### Geometry and timing - The bsnes-jg core's core provided FPS is 60.098812 for NTSC games and 50.006979 for PAL games. - The bsnes-jg core's core provided sample rate is 48000Hz - The bsnes-jg core provides adjustable overscan and aspect ratio options. ## Subsystems bsnes-jg supports Super Game Boy, BS-X Satellaview, and Sufami Turbo via the Subsystem API. For Super Game Boy, you will need a Game Boy ROM (.gb/gbc) and Super Game Boy ROM. For BS-X Satellaview, you will need a BS Memory dump (.bs) and BS-X BIOS ROM. For Sufami Turbo (1 or 2 Carts), you will need Sufami Turbo ROMs (.st) and the Sufami Turbo ROM. | Subsystem | Description | |:---------:|:-----------------------------:| | sgb | Super Game Boy | | bsx | BS-X Satellaview | | sufami | Sufami Turbo (One Cart) | | sufami2 | Sufami Turbo (Two Carts) | **Command Line** ``` retroarch -L {path to bsnes core} {path to Super GameBoy ROM} --subsystem sgb {path to GameBoy rom} ``` **RetroArch GUI** Load the Game Boy ROM through 'Load SuperGame Boy' in RetroArch's Main Menu. ![](../image/core/bsnes/menu1.png) ![](../image/core/bsnes/gb.png) Next, load the Super Game Boy BIOS ROM through 'Load Super GameBoy' in RetroArch's Menu Menu. ![](../image/core/bsnes/menu2.png) ![](../image/core/bsnes/sgb.png) Then, start the content by selecting 'Start GameBoy' In RetroArch's Menu Menu. ![](../image/core/bsnes/start.png) ## MSU-1 MSU-1 is supported. To load an MSU-1 enhanced ROM, simply load the .sfc which resides in the same directory as the .msu and audio tracks. ## Core options - **Delay LLE Coprocessor Sync (Restart)** [bsnes_jg_coproc_delaysync] (**Off**|On) Delay sync when using Low Level Coprocessor Emulation for more speed at the cost of accuracy - **Prefer HLE Coprocessor Emulation (Restart)** [bsnes_jg_coproc_preferhle] (**Off**|On) Delay sync when using Low Level Coprocessor Emulation for more speed at the cost of accuracy - **Hotfixes (Restart)** [bsnes_jg_hotfixes] (**Off**|On) Apply hotfixes when playing a handful of games released with major bugs (which are exhibited on real hardware). Games in question: Dirt Racer, Magical Drop, Rendering Ranger R2 - **Internal Run-Ahead** [bsnes_jg_runahead] (**0**|1|2|3|4) Simulate the system ahead of time and roll back to reduce input latency. Has very high system requirements. - **Resampler Quality (Restart)** [bsnes_jg_rsqual] (**Fast**|Medium|Best) Set the internal resampler's quality level (you may hear a difference if you use pro audio equipment and your imagination) - **SPC Interpolation Algorithm** [bsnes_jg_spc_interp] (**Gaussian**|Sinc) Set the emulated sound chip sample interpolation algorithm: Gaussian is considered more accurate, while Sinc is cleaner, but still produces very accurate output. - **Aspect Ratio** [bsnes_jg_aspect] (**Auto**|1:1|8:7|11:8|4:3) Set the Aspect Ratio - **Mask Overscan (Top)** [bsnes_jg_overscan_t] (0|4|**8**|12|16|20) Mask off pixels hidden by a bezel or border on original CRTs (top) - **Mask Overscan (Bottom)** [bsnes_jg_overscan_b] (0|4|**8**|12|16|20|21) Mask off pixels hidden by a bezel or border on original CRTs (bottom) - **Mask Overscan (Left)** [bsnes_jg_overscan_l] (**0**|4|8|12|16|20) Mask off pixels hidden by a bezel or border on original CRTs (left) - **Mask Overscan (Right)** [bsnes_jg_overscan_r] (**0**|4|8|12|16|20) Mask off pixels hidden by a bezel or border on original CRTs (right) - **Colour Adjustment - Luminance** [bsnes_jg_luminance] (0%|10%|20%|30%|40%|50%|60%|70%|80%|90%|**100%**) Adjust Luminance - **Colour Adjustment - Saturation** [bsnes_jg_saturation] (0%|10%|20%|30%|40%|50%|60%|70%|80%|90%|**100%**|110%|120%|130%|140%|150%|160%|170%|180%|190%|200%) Adjust Saturation - **Colour Adjustment - Gamma** [bsnes_jg_gamma] (100%|110%|**120%**|130%|140%|150%|160%|170%|180%|190%|200%) Adjust Gamma - **Competition Timer** [bsnes_jg_competition_timer] (3 Minutes|4 Minutes|5 Minutes|**6 Minutes**|7 Minutes|8 Minutes|9 Minutes|10 Minutes|11 Minutes|12 Minutes|13 Minutes|14 Minutes|15 Minutes|16 Minutes|17 Minutes|18 Minutes) Set the gameplay time for competition boards such as Campus Challenge '92 and PowerFest '94 ## Controllers The bsnes-jg core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - **[Gamepad](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller)** - Gamepad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse ### User 2 device types - **[Gamepad](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller)** - Gamepad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse - [Multitap](http://nintendo.wikia.com/wiki/Super_Multitap) - Gamepad - Allows for up to five players to play together in multitap games. - [SuperScope](https://en.wikipedia.org/wiki/Super_Scope) - Lightgun - [Justifier](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun ### Multitap support Activating multitap support in compatible games can be configured by switching to the [Multitap device type](#controllers) for User 2. ### Controller tables #### Gamepad ![](../image/controller/snes.png) | User 1 - 5 Remap descriptors | RetroPad Inputs | |------------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Y | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | X | ![](../image/retropad/retro_x.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | #### Mouse | RetroMouse Inputs | SNES Mouse | |-------------------------------------------------------|---------------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | SNES Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | SNES Mouse Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | SNES Mouse Right Button | #### Lightgun | RetroLightgun Inputs | SuperScope | Justifier(s) | |--------------------------------------------------------|---------------------------|---------------------| | ![](../image/retromouse/retro_mouse.png) Gun Crosshair | SuperScope Crosshair | Justifier Crosshair | | Gun Trigger | SuperScope Trigger | Justifier Trigger | | Gun Aux A | SuperScope Cursor | | | Gun Aux B | SuperScope Turbo | | | Gun Start | SuperScope Pause | Justifier Start | ## Compatibility The bsnes-jg core is compatible with all officially released SNES/SFC titles. ## External Links - [Upstream bsnes-jg Repository](https://gitlab.com/jgemu/bsnes-jg) - [Libretro bsnes-jg Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/bsnes-jg_libretro.info) - [Libretro bsnes-jg Repository](https://github.com/libretro/bsnes-jg) - [Report bsnes-jg Core Issues Here](https://github.com/libretro/bsnes-jg/issues) ### See also #### Nintendo - Sufami Turbo - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) #### Nintendo - Super Nintendo Entertainment System (+ Hacks) - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (higan Accuracy)](higan_accuracy.md) - [Nintendo - SNES / Famicom (nSide Balanced)](nside_balanced.md) - [Nintendo - SNES / Famicom (Mesen-S)](mesen-s.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) ================================================ FILE: docs/library/bsnes_accuracy.md ================================================ # Nintendo - SNES / Famicom (bsnes Accuracy) ## Background bsnes is a Super Nintendo emulator that began development on 2004-10-14. It focuses on accuracy and clean code above all else. It never uses speed or compatibility hacks. As a result, the minimum system requirements are greater than with other emulators. bsnes comes in three different profiles (accuracy, balanced and performance) which contain minor differences in the PPU (graphics) emulation. This core has been compiled with the Accuracy profile. Highly accurate SNES emulation. Whether to use the Accuracy, or Balanced or Performance core depends on how much accuracy you want to give up for game performance. Please check the [compatibility section](#compatibility) for more information. ### Author/License The bsnes Accuracy core has been authored by - byuu The bsnes Accuracy core is licensed under - [GPLv3](https://github.com/libretro/bsnes-libretro/blob/libretro/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the bsnes Accuracy core have the following file extensions: - .sfc - .smc - .bml ## Databases RetroArch database(s) that are associated with the bsnes Accuracy core: - [Nintendo - Super Nintendo Entertainment System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System.rdb) - [Nintendo - Super Nintendo Entertainment System Hacks](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System%20Hacks.rdb) - [Nintendo - Sufami Turbo](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Sufami%20Turbo.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. !!! attention The bsnes Accuracy core uses split ROMS for [special chip games](https://en.wikipedia.org/wiki/List_of_Super_NES_enhancement_chips#List_of_Super_NES_games_that_use_enhancement_chips). Notable DSP1/DSP1B Games: - Super Mario Kart - Pilotwings Notable DSP2 Games: - Dungeon Master Notable DSP3 Games: - SD Gundam GX Notable DSP4 Games: - Top Gear 3000 Notable Cx4 Games: - Mega Man X2 - Mega Man X3 | Filename | Description | md5sum | |:-----------------:|:--------------------------------------:|:--------------------------------:| | dsp1.data.rom | DSP1 co-processor firmware | 3d81b45fa0c2aa8b852dfb1ece7c0971 | | dsp1.program.rom | DSP1 co-processor firmware | ae209fbe789fbf11a48aea5ab1197321 | | dsp1b.data.rom | DSP1B co-processor firmware | 1e3f568634a7d8284020dddc0ae905bc | | dsp1b.program.rom | DSP1B co-processor firmware | d10f446888e097cbf500f3f663cf4f6d | | dsp2.data.rom | DSP2 co-processor firmware | e9417e29223b139c3c4b635a2a3b8744 | | dsp2.program.rom | DSP2 co-processor firmware | aa6e5922a3ed5ded54f24247c11143c5 | | dsp3.data.rom | DSP3 co-processor firmware | 0a81210c0a940b997dd9843281008ee6 | | dsp3.program.rom | DSP3 co-processor firmware | d99ca4562818d49cee1f242705bba6f8 | | dsp4.data.rom | DSP4 co-processor firmware | ee4990879eb68e3cbca239c5bc20303d | | dsp4.program.rom | DSP4 co-processor firmware | a151023b948b90ffc23a5b594bb6fef2 | | cx4.data.rom | CX4 co-processor firmware | 037ac4296b6b6a5c47c440188d3c72e3 | | st010.data.rom | ST010 co-processor firmware | 254d70762b6f59f99c27c395aba7d07d | | st010.program.rom | ST010 co-processor firmware | 1d70019179a59a566a0bb5d3f2845544 | | st011.data.rom | ST011 co-processor firmware | 10bd3f4aa949737ab9836512c35bcc29 | | st011.program.rom | ST011 co-processor firmware | 95222ebf1c0c2990bcf25db43743f032 | | st018.data.rom | ST018 co-processor firmware | 49c898b60d0f15e90d0ba780dd12f366 | | st018.program.rom | ST018 co-processor firmware | dda40ccd57390c96e49d30a041f9a9e7 | | sgb.boot.rom | Super Game Boy BIOS | | ## Features Frontend-level settings or features that the bsnes Accuracy core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | - | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✔ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✔ | | LEDs | ✕ | ### Directories The bsnes Accuracy core's internal core name is 'bsnes' The bsnes Accuracy core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.srm (Cartridge battery save) **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The bsnes Accuracy core's core provided FPS is 60.0988118623 for NTSC games and 50.0069789082 for PAL games. - The bsnes Accuracy core's core provided sample rate is 32040.5 Hz - The bsnes Accuracy core's core provided aspect ratio is 4/3 ## Super GameBoy !!! warning Super GameBoy support in this core is **Windows only**, and has **buggy save state support** and **visual glitches**. **Use the [higan Accuracy core](higan_accuracy.md#super-gameboy-support) or the [nSide Balanced core](nside_balanced.md#super-gameboy-support) for simplified, functional, and easily accessible Super Gameboy support.** For Super GameBoy support, you need sgb.boot.rom (in RetroArch's System directory), a GameBoy ROM and a Super GameBoy ROM. Please note that the Game Boy and Super GameBoy ROMs have to be unzipped. Super GameBoy is supported via the Subsystem API. There are two ways to access the Subsystem API. **One way is to access the Subsystem API through RetroArch's GUI like this.** First, we load our GameBoy ROM through 'Load Super GameBoy' in RetroArch's Main Menu. ![](../image/core/bsnes/menu1.png) ![](../image/core/bsnes/gb.png) Next, we load our Super GameBoy ROM through 'Load Super GameBoy' in RetroArch's Menu Menu. ![](../image/core/bsnes/menu2.png) ![](../image/core/bsnes/sgb.png) Then, we start the content by selecting 'Start GameBoy' In RetroArch's Menu Menu. ![](../image/core/bsnes/start.png) **The other way is to launch RetroArch with commandline like this.** ``` retroarch -L {path to bsnes core} {path to Super GameBoy ROM} --subsystem sgb {path to GameBoy rom} ``` ## MSU-1 !!! attention MSU-1 support in this core is complex. **Use the [Snes9x core](../library/snes9x#msu-1-support) for simplified and easily accessible MSU-1 support.** MSU-1 support can be used by loading a correct .bml file. There's documentation for loading MSU-1 games in standalone higan [here](https://higan.readthedocs.io/en/stable/guides/import/#msu-1-games). ## Controllers The bsnes Accuracy core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Disables input. - **[SNES Joypad](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller)** - Joypad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse ### User 2 device types - None - Disables input. - **[SNES Joypad](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller)** - Joypad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse - [Multitap](http://nintendo.wikia.com/wiki/Super_Multitap) - Joypad - Allows for up to five players to play together in multitap games. - [SuperScope](https://en.wikipedia.org/wiki/Super_Scope) - Lightgun - [Justifier](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - [Justifiers](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - Two Justifiers are plugged in, for two-player Justifier games. ### Multitap support Activating multitap support in compatible games can be configured by switching to the [Multitap device type](#controllers) for User 2. ### Controller tables #### Joypad ![](../image/controller/snes.png) | User 1 - 5 Remap descriptors | RetroPad Inputs | |------------------------------|-------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Y | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | X | ![](../image/retropad/retro_x.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | #### Mouse | RetroMouse Inputs | SNES Mouse | |-----------------------------------------------------|---------------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | SNES Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | SNES Mouse Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | SNES Mouse Right Button | #### Lightgun | RetroLightgun Inputs | SuperScope | Justifier(s) | |------------------------------------------------------|---------------------------|---------------------| | ![](../image/retromouse/retro_mouse.png) Gun Crosshair | SuperScope Crosshair | Justifier Crosshair | | Gun Trigger | SuperScope Trigger | Justifier Trigger | | Gun Aux A | SuperScope Cursor | | | Gun Aux B | SuperScope Turbo | | | Gun Start | SuperScope Pause | Justifier Start | ## Compatibility The bsnes Accuracy core fully emulates all SNES games that have ever been officially released. ## External Links - [Official higan Website](https://byuu.org/) - [Official higan Upstream Downloads](https://byuu.org/emulation/higan/) - [Libretro bsnes Accuracy Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/bsnes_accuracy_libretro.info) - [Libretro bsnes Accuracy Github Repository](https://github.com/libretro/bsnes-libretro) - [Report Libretro bsnes Accuracy Core Issues Here](https://github.com/libretro/bsnes-libretro/issues) ### See also #### Nintendo - Sufami Turbo - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-jg)](bsnes-jg.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) #### Nintendo - Super Nintendo Entertainment System (+ Hacks) - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-jg)](bsnes-jg.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (higan Accuracy)](higan_accuracy.md) - [Nintendo - SNES / Famicom (nSide Balanced)](nside_balanced.md) - [Nintendo - SNES / Famicom (Mesen-S)](mesen-s.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) ================================================ FILE: docs/library/bsnes_balanced.md ================================================ # Nintendo - SNES / Famicom (bsnes Balanced) ## Background bsnes is a Super Nintendo emulator that began development on 2004-10-14. It focuses on accuracy and clean code above all else. It never uses speed or compatibility hacks. As a result, the minimum system requirements are greater than with other emulators. bsnes comes in three different profiles (accuracy, balanced and performance) which contain minor differences in the PPU (graphics) emulation. This core has been compiled with the Balanced profile. Highly accurate SNES emulation. Whether to use the Accuracy, or Balanced or Performance core depends on how much accuracy you want to give up for game performance. Please check the [compatibility section](#compatibility) for more information. ### Author/License The bsnes Balanced core has been authored by - byuu The bsnes Balanced core is licensed under - [GPLv3](https://github.com/libretro/bsnes-libretro/blob/libretro/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the bsnes Balanced core have the following file extensions: - .sfc - .smc - .bml ## Databases RetroArch database(s) that are associated with the bsnes Balanced core: - [Nintendo - Super Nintendo Entertainment System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System.rdb) - [Nintendo - Super Nintendo Entertainment System Hacks](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System%20Hacks.rdb) - [Nintendo - Sufami Turbo](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Sufami%20Turbo.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. !!! attention The bsnes Balanced core uses split ROMS for [special chip games](https://en.wikipedia.org/wiki/List_of_Super_NES_enhancement_chips#List_of_Super_NES_games_that_use_enhancement_chips). Notable DSP1/DSP1B Games: - Super Mario Kart - Pilotwings Notable DSP2 Games: - Dungeon Master Notable DSP3 Games: - SD Gundam GX Notable DSP4 Games: - Top Gear 3000 Notable Cx4 Games: - Mega Man X2 - Mega Man X3 | Filename | Description | md5sum | |:-----------------:|:--------------------------------------:|:--------------------------------:| | dsp1.data.rom | DSP1 co-processor firmware | 3d81b45fa0c2aa8b852dfb1ece7c0971 | | dsp1.program.rom | DSP1 co-processor firmware | ae209fbe789fbf11a48aea5ab1197321 | | dsp1b.data.rom | DSP1B co-processor firmware | 1e3f568634a7d8284020dddc0ae905bc | | dsp1b.program.rom | DSP1B co-processor firmware | d10f446888e097cbf500f3f663cf4f6d | | dsp2.data.rom | DSP2 co-processor firmware | e9417e29223b139c3c4b635a2a3b8744 | | dsp2.program.rom | DSP2 co-processor firmware | aa6e5922a3ed5ded54f24247c11143c5 | | dsp3.data.rom | DSP3 co-processor firmware | 0a81210c0a940b997dd9843281008ee6 | | dsp3.program.rom | DSP3 co-processor firmware | d99ca4562818d49cee1f242705bba6f8 | | dsp4.data.rom | DSP4 co-processor firmware | ee4990879eb68e3cbca239c5bc20303d | | dsp4.program.rom | DSP4 co-processor firmware | a151023b948b90ffc23a5b594bb6fef2 | | cx4.data.rom | CX4 co-processor firmware | 037ac4296b6b6a5c47c440188d3c72e3 | | st010.data.rom | ST010 co-processor firmware | 254d70762b6f59f99c27c395aba7d07d | | st010.program.rom | ST010 co-processor firmware | 1d70019179a59a566a0bb5d3f2845544 | | st011.data.rom | ST011 co-processor firmware | 10bd3f4aa949737ab9836512c35bcc29 | | st011.program.rom | ST011 co-processor firmware | 95222ebf1c0c2990bcf25db43743f032 | | st018.data.rom | ST018 co-processor firmware | 49c898b60d0f15e90d0ba780dd12f366 | | st018.program.rom | ST018 co-processor firmware | dda40ccd57390c96e49d30a041f9a9e7 | | sgb.boot.rom | Super Game Boy BIOS | | ## Features Frontend-level settings or features that the bsnes Balanced core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | - | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✔ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✔ | | LEDs | ✕ | ### Directories The bsnes Balanced core's internal core name is 'bsnes' The bsnes Balanced core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.srm (Cartridge battery save) **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The bsnes Balanced core's core provided FPS is 60.0988118623 for NTSC games and 50.0069789082 for PAL games. - The bsnes Balanced core's core provided sample rate is 32040.5 Hz - The bsnes Balanced core's core provided aspect ratio is 4/3 ## Super GameBoy !!! warning Super GameBoy support in this core is **Windows only**, and has **buggy save state support** and **visual glitches**. **Use the [higan Accuracy core](higan_accuracy.md#super-gameboy-support) or the [nSide Balanced core](nside_balanced.md#super-gameboy-support) for simplified, functional, and easily accessible Super Gameboy support.** For Super GameBoy support, you need sgb.boot.rom (in RetroArch's System directory), a GameBoy ROM and a Super GameBoy ROM. Please note that the Game Boy and Super GameBoy ROMs have to be unzipped. Super GameBoy is supported via the Subsystem API. There are two ways to access the Subsystem API. **One way is to access the Subsystem API through RetroArch's GUI like this.** First, we load our GameBoy ROM through 'Load Super GameBoy' in RetroArch's Main Menu. ![](../image/core/bsnes/menu1.png) ![](../image/core/bsnes/gb.png) Next, we load our Super GameBoy ROM through 'Load Super GameBoy' in RetroArch's Menu Menu. ![](../image/core/bsnes/menu2.png) ![](../image/core/bsnes/sgb.png) Then, we start the content by selecting 'Start GameBoy' In RetroArch's Menu Menu. ![](../image/core/bsnes/start.png) **The other way is to launch RetroArch with commandline like this.** ``` retroarch -L {path to bsnes core} {path to Super GameBoy ROM} --subsystem sgb {path to GameBoy rom} ``` ## MSU-1 !!! attention MSU-1 support in this core is complex. **Use the [Snes9x core](snes9x.md#msu-1-support) for simplified and easily accessible MSU-1 support.** MSU-1 support can be used by loading a correct .bml file. There's documentation for loading MSU-1 games in standalone higan [here](https://higan.readthedocs.io/en/stable/guides/import/#msu-1-games). ## Controllers The bsnes Balanced core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Disables input. - **[SNES Joypad](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller)** - Joypad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse ### User 2 device types - None - Disables input. - **[SNES Joypad](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller)** - Joypad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse - [Multitap](http://nintendo.wikia.com/wiki/Super_Multitap) - Joypad - Allows for up to five players to play together in multitap games. - [SuperScope](https://en.wikipedia.org/wiki/Super_Scope) - Lightgun - [Justifier](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - [Justifiers](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - Two Justifiers are plugged in, for two-player Justifier games. ### Multitap support Activating multitap support in compatible games can be configured by switching to the [Multitap device type](#controllers) for User 2. ### Controller tables #### Joypad ![](../image/controller/snes.png) | User 1 - 5 Remap descriptors | RetroPad Inputs | |------------------------------|-------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Y | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | X | ![](../image/retropad/retro_x.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | #### Mouse | RetroMouse Inputs | SNES Mouse | |-----------------------------------------------------|---------------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | SNES Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | SNES Mouse Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | SNES Mouse Right Button | #### Lightgun | RetroLightgun Inputs | SuperScope | Justifier(s) | |------------------------------------------------------|---------------------------|---------------------| | ![](../image/retromouse/retro_mouse.png) Gun Crosshair | SuperScope Crosshair | Justifier Crosshair | | Gun Trigger | SuperScope Trigger | Justifier Trigger | | Gun Aux A | SuperScope Cursor | | | Gun Aux B | SuperScope Turbo | | | Gun Start | SuperScope Pause | Justifier Start | ## Compatibility | Game | Issue | |--------------------------|--------------------------------------------------------------------------------| | A.S.P. Air Strike Patrol | Black lines show up during gameplay. The shadow below the aircraft is missing. | ## External Links - [Official higan Website](https://byuu.org/) - [Official higan Upstream Downloads](https://byuu.org/emulation/higan/) - [Libretro bsnes Balanced Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/bsnes_balanced_libretro.info) - [Libretro bsnes Balanced Github Repository](https://github.com/libretro/bsnes-libretro) - [Report Libretro bsnes Balanced Core Issues Here](https://github.com/libretro/bsnes-libretro/issues) ### See also #### Nintendo - Sufami Turbo - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-jg)](bsnes-jg.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) #### Nintendo - Super Nintendo Entertainment System (+ Hacks) - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-jg)](bsnes-jg.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (higan Accuracy)](higan_accuracy.md) - [Nintendo - SNES / Famicom (nSide Balanced)](nside_balanced.md) - [Nintendo - SNES / Famicom (Mesen-S)](mesen-s.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) ================================================ FILE: docs/library/bsnes_cplusplus98.md ================================================ # Nintendo - SNES / Famicom (bsnes C++98 (v085)) ## Background bsnes c++98 is a special fork from around v085 that's been backported to work with older compilers. Many platforms Libretro supports such as various consoles (PlayStation 3) are stuck with super-old compilers that don't support the latest c++ features that are in the newer bsnes v094 ports. There's no reason to use this core now expect for edge cases on less compatible platforms. ### Author/License The bsnes C++98 (v085) core has been authored by - byuu - Themaister - Ver GreenEyes The bsnes C++98 (v085) core is licensed under - [GPLv3](https://github.com/libretro/bsnes-libretro/blob/libretro/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the bsnes C++98 (v085) core have the following file extensions: - .sfc - .smc ## Databases RetroArch database(s) that are associated with the bsnes C++98 (v085) core: - [Nintendo - Super Nintendo Entertainment System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System.rdb) - [Nintendo - Super Nintendo Entertainment System Hacks](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System%20Hacks.rdb) - [Nintendo - Sufami Turbo](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Sufami%20Turbo.rdb) ## Features Frontend-level settings or features that the bsnes C++98 (v085) core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✔ | | LEDs | ✕ | ### Directories The bsnes C++98 (v085) core's internal core name is '"bSNES' The bsnes C++98 (v085) core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.srm (Cartridge battery save) **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The bsnes C++98 (v085) core's core provided FPS is 60.0988118623 for NTSC games and 50.0069789082 for PAL games. - The bsnes C++98 (v085) core's core provided sample rate is 32040.5 Hz. - The bsnes C++98 (v085) core's core provided aspect ratio is (Ratio) ## Controllers The bsnes C++98 (v085) core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. - **[SNES Joypad](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller)** - Joypad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse ### User 2 device types - None - Doesn't disable input. - **[SNES Joypad](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller)** - Joypad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse - [Multitap](http://nintendo.wikia.com/wiki/Super_Multitap) - Joypad - Allows for up to five players to play together in mulitap games. - [SuperScope](https://en.wikipedia.org/wiki/Super_Scope) - Lightgun - [Justifier](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - [Justifiers](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - Two Justifiers are plugged in, for two-player Justifier games. ### Multitap support Activating multitap support in compatible games can be configured by switching to the [Multitap device type](#controllers) for User 2. ### Controller tables #### Joypad ![](../image/controller/snes.png) | User 1 - 5 Remap descriptors | RetroPad Inputs | |------------------------------|-------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Y | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | X | ![](../image/retropad/retro_x.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | #### Mouse | RetroMouse Inputs | SNES Mouse | |-------------------------------------------------------|---------------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | SNES Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | SNES Mouse Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | SNES Mouse Right Button | #### Lightgun | RetroLightgun Inputs | SuperScope | Justifier(s) | |--------------------------------------------------------|---------------------------|---------------------| | ![](../image/retromouse/retro_mouse.png) Gun Crosshair | SuperScope Crosshair | Justifier Crosshair | | Gun Trigger | SuperScope Trigger | Justifier Trigger | | Gun Aux A | SuperScope Cursor | | | Gun Aux B | SuperScope Turbo | | | Gun Start | SuperScope Pause | Justifier Start | ## Compatibility Awaiting description. ## External Links - [Official higan Website](https://byuu.org/) - [Official higan Upstream Downloads](https://byuu.org/emulation/higan/) - [Libretro bsnes C++98 (v085) Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/bsnes_cplusplus98_libretro.info) - [Libretro bsnes C++98 (v085) Github Repository](https://github.com/libretro/bsnes-libretro-cplusplus98) - [Report Libretro bsnes C++98 (v085) Core Issues Here](https://github.com/libretro/bsnes-libretro-cplusplus98/issues) ### See also #### Nintendo - Sufami Turbo - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-jg)](bsnes-jg.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) #### Nintendo - Super Nintendo Entertainment System (+ Hacks) - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-jg)](bsnes-jg.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (higan Accuracy)](higan_accuracy.md) - [Nintendo - SNES / Famicom (nSide Balanced)](nside_balanced.md) - [Nintendo - SNES / Famicom (Mesen-S)](mesen-s.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) ================================================ FILE: docs/library/bsnes_mercury_accuracy.md ================================================ # Nintendo - SNES / Famicom (bsnes-mercury Accuracy) ## Background bsnes-mercury is a fork of higan, aiming to restore some useful features that have been removed, as well as improving performance a bit. Maximum accuracy is still uncompromising; anything that affects accuracy is optional and off by default. This core has been compiled with the Accuracy profile. Improvements include: * Improved framerate * Faster ROM loading * HLE emulation of some special chips is optionally restored (defaults to LLE), to improve performance and reduce reliance on those chip ROMs (they're not really easy to find). Chips for which no HLE emulation was developed (ST-0011 and ST-0018) are still LLE. * SuperFX overclock is now available (off by default, of course); if enabled, it makes SuperFX look quite a lot smoother. **The bsnes-mercury cores are not less accurate at default settings than the mainline bsnes cores (you have to explicitly enable 2 core options to switch to the less accurate special chip HLE).** ### Author/License The bsnes-mercury Accuracy core has been authored by - byuu - Alcaro The bsnes-mercury Accuracy core is licensed under - [GPLv3](https://github.com/libretro/bsnes-mercury/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the bsnes-mercury Accuracy core have the following file extensions: - .sfc - .smc - .bml ## Databases RetroArch database(s) that are associated with the bsnes-mercury Accuracy core: - [Nintendo - Super Nintendo Entertainment System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System.rdb) - [Nintendo - Super Nintendo Entertainment System Hacks](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System%20Hacks.rdb) - [Nintendo - Sufami Turbo](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Sufami%20Turbo.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:-----------------:|:--------------------------------------:|:--------------------------------:| | dsp1.data.rom | DSP1 co-processor firmware | 3d81b45fa0c2aa8b852dfb1ece7c0971 | | dsp1.program.rom | DSP1 co-processor firmware | ae209fbe789fbf11a48aea5ab1197321 | | dsp1b.data.rom | DSP1B co-processor firmware | 1e3f568634a7d8284020dddc0ae905bc | | dsp1b.program.rom | DSP1B co-processor firmware | d10f446888e097cbf500f3f663cf4f6d | | dsp2.data.rom | DSP2 co-processor firmware | e9417e29223b139c3c4b635a2a3b8744 | | dsp2.program.rom | DSP2 co-processor firmware | aa6e5922a3ed5ded54f24247c11143c5 | | dsp3.data.rom | DSP3 co-processor firmware | 0a81210c0a940b997dd9843281008ee6 | | dsp3.program.rom | DSP3 co-processor firmware | d99ca4562818d49cee1f242705bba6f8 | | dsp4.data.rom | DSP4 co-processor firmware | ee4990879eb68e3cbca239c5bc20303d | | dsp4.program.rom | DSP4 co-processor firmware | a151023b948b90ffc23a5b594bb6fef2 | | cx4.data.rom | CX4 co-processor firmware | 037ac4296b6b6a5c47c440188d3c72e3 | | st010.data.rom | ST010 co-processor firmware | 254d70762b6f59f99c27c395aba7d07d | | st010.program.rom | ST010 co-processor firmware | 1d70019179a59a566a0bb5d3f2845544 | | st011.data.rom | ST011 co-processor firmware | 10bd3f4aa949737ab9836512c35bcc29 | | st011.program.rom | ST011 co-processor firmware | 95222ebf1c0c2990bcf25db43743f032 | | st018.data.rom | ST018 co-processor firmware | 49c898b60d0f15e90d0ba780dd12f366 | | st018.program.rom | ST018 co-processor firmware | dda40ccd57390c96e49d30a041f9a9e7 | | sgb.boot.rom | Super Game Boy BIOS | | ## Features Frontend-level settings or features that the bsnes-mercury Accuracy core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | - | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✔ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The bsnes-mercury Accuracy core's internal core name is 'bsnes-mercury' The bsnes-mercury Accuracy core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.srm (Cartridge battery save) **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The bsnes-mercury Accuracy core's core provided FPS is 60.0988118623 for NTSC games and 50.0069789082 for PAL games. - The bsnes-mercury Accuracy core's core provided sample rate is 32040.5 Hz - The bsnes-mercury Accuracy core's core provided aspect ratio is dependent on the ['Preferred aspect ratio' core option](#core-options). ## Super GameBoy !!! warning Super GameBoy support in this core is **Windows only**, and has **buggy save state support** and **visual glitches**. **Use the [higan Accuracy core](higan_accuracy.md#super-gameboy-support) or the [nSide Balanced core](nside_balanced.md#super-gameboy-support) for simplified, functional, and easily accessible Super Gameboy support.** For Super GameBoy support, you need sgb.boot.rom (in RetroArch's System directory), a GameBoy ROM and a Super GameBoy ROM. Please note that the Game Boy and Super GameBoy ROMs have to be unzipped. Super GameBoy is supported via the Subsystem API. There are two ways to access the Subsystem API. **One way is to access the Subsystem API through RetroArch's GUI like this.** First, we load our GameBoy ROM through 'Load Super GameBoy' in RetroArch's Main Menu. ![](../image/core/bsnes/menu1.png) ![](../image/core/bsnes/gb.png) Next, we load our Super GameBoy ROM through 'Load Super GameBoy' in RetroArch's Menu Menu. ![](../image/core/bsnes/menu2.png) ![](../image/core/bsnes/sgb.png) Then, we start the content by selecting 'Start GameBoy' In RetroArch's Menu Menu. ![](../image/core/bsnes/start.png) **The other way is to launch RetroArch with commandline like this.** ``` retroarch -L {path to bsnes core} {path to Super GameBoy ROM} --subsystem sgb {path to GameBoy rom} ``` ## MSU-1 !!! attention MSU-1 support in this core is complex. **Use the [Snes9x core](snes9x.md#msu-1-support) for simplified and easily accessible MSU-1 support.** MSU-1 support can be used by loading a correct .bml file. There's documentation for loading MSU-1 games in standalone higan [here](https://higan.readthedocs.io/en/stable/guides/import/#msu-1-games). ## Core options The bsnes-mercury Accuracy core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Allow settings to reduce accuracy** [bsnes_violate_accuracy] (**disabled**|enabled) Respect accuracy-impacting settings. - **Special chip accuracy** [bsnes_chip_hle] (**LLE**|HLE) **The Allow settings to reduce accuracy core option must be enabled in order for this to function properly. ** Choose whether to use LLE (real BIOS) or HLE (emulated BIOS) for enhancement chips. HLE is less accurate but also less demanding for the special chips. The ST-0011 and ST-0018 co-processors cannot be HLE'd. - **SuperFX speed** [bsnes_superfx_overclock] (**100%**|150%|200%|300%|400%|500%|1000%) **The Allow settings to reduce accuracy core option must be enabled in order for this to function properly.** Overclock the [SuperFX chip](https://en.wikipedia.org/wiki/Super_FX). 100% is stock clockspeed. - **System region** [bsnes_region] (**auto**|ntsc|pal) Choose which region the system is from. - **Preferred aspect ratio** [bsnes_aspect_ratio] (**auto**|ntsc|pal) Choose the preferred aspect ratio. RetroArch's aspect ratio must be set to Core provided in the Video settings. - **Crop overscan** [bsnes_crop_overscan] (**disabled**|enabled) Crop out the potentially random glitchy video output that would have been hidden by the bezel around the edge of a standard-definition television screen. - **Gamma ramp (requires restart)** [bsnes_gamma_ramp] (**disabled**|enabled) Simulates the way a console’s display device differs from modern computer monitor’s colour reproduction. In particular, it simulates the slightly-different gamma correction used by the Super Famicom. ??? note "Gamma ramp - Disabled" ![](../image/core/higan/gamma_off.png) ??? note "Gamma ramp - Enabled" ![](../image/core/higan/gamma_on.png) ## Controllers The bsnes-mercury Accuracy core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. - **[SNES Joypad](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller)** - Joypad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse ### User 2 device types - None - Doesn't disable input. - **[SNES Joypad](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller)** - Joypad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse - [Multitap](http://nintendo.wikia.com/wiki/Super_Multitap) - Joypad - Allows for up to five players to play together in multitap games. - [SuperScope](https://en.wikipedia.org/wiki/Super_Scope) - Lightgun - [Justifier](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - [Justifiers](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - Two Justifiers are plugged in, for two-player Justifier games. ### Multitap support Activating multitap support in compatible games can be configured by switching to the [Multitap device type](#controllers) for User 2. ### Controller tables #### Joypad ![](../image/controller/snes.png) | User 1 - 5 Remap descriptors | RetroPad Inputs | |------------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Y | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | X | ![](../image/retropad/retro_x.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | #### Mouse | RetroMouse Inputs | SNES Mouse | |-------------------------------------------------------|---------------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | SNES Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | SNES Mouse Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | SNES Mouse Right Button | #### Lightgun | RetroLightgun Inputs | SuperScope | Justifier(s) | |--------------------------------------------------------|---------------------------|---------------------| | ![](../image/retromouse/retro_mouse.png) Gun Crosshair | SuperScope Crosshair | Justifier Crosshair | | Gun Trigger | SuperScope Trigger | Justifier Trigger | | Gun Aux A | SuperScope Cursor | | | Gun Aux B | SuperScope Turbo | | | Gun Start | SuperScope Pause | Justifier Start | ## Compatibility The bsnes-mercury Accuracy core fully emulates all SNES games that have ever been officially released. ## External Links - [Official higan Website](https://byuu.org/) - [Official higan Upstream Downloads](https://byuu.org/emulation/higan/) - [Libretro bsnes-mercury Accuracy Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/bsnes_mercury_accuracy_libretro.info) - [Libretro bsnes-mercury Accuracy Github Repository](https://github.com/libretro/bsnes-mercury) - [Report Libretro bsnes-mercury Accuracy Core Issues Here](https://github.com/libretro/bsnes-mercury/issues) ### See also #### Nintendo - Sufami Turbo - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-jg)](bsnes-jg.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) #### Nintendo - Super Nintendo Entertainment System (+ Hacks) - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-jg)](bsnes-jg.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (higan Accuracy)](higan_accuracy.md) - [Nintendo - SNES / Famicom (nSide Balanced)](nside_balanced.md) - [Nintendo - SNES / Famicom (Mesen-S)](mesen-s.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) ================================================ FILE: docs/library/bsnes_mercury_balanced.md ================================================ # Nintendo - SNES / Famicom (bsnes-mercury Balanced) ## Background bsnes-mercury is a fork of higan, aiming to restore some useful features that have been removed, as well as improving performance a bit. Maximum accuracy is still uncompromisable; anything that affects accuracy is optional and off by default. This core has been compiled with the Balanced profile. Improvements include: * Improved framerate * Faster ROM loading * HLE emulation of some special chips is optionally restored (defaults to LLE), to improve performance and reduce reliance on those chip ROMs (they're not really easy to find). Chips for which no HLE emulation was developed (ST-0011 and ST-0018) are still LLE. * SuperFX overclock is now available (off by default, of course); if enabled, it makes SuperFX look quite a lot smoother. **The bsnes-mercury cores are not less accurate at default settings than the mainline bsnes cores (you have to explicitly enable 2 core options to switch to the less accurate special chip HLE).** ### Author/License The bsnes-mercury Balanced core has been authored by - byuu - Alcaro The bsnes-mercury Balanced core is licensed under - [GPLv3](https://github.com/libretro/bsnes-mercury/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the bsnes-mercury Balanced core have the following file extensions: - .sfc - .smc - .bml ## Databases RetroArch database(s) that are associated with the bsnes-mercury Balanced core: - [Nintendo - Super Nintendo Entertainment System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System.rdb) - [Nintendo - Super Nintendo Entertainment System Hacks](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System%20Hacks.rdb) - [Nintendo - Sufami Turbo](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Sufami%20Turbo.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:-----------------:|:--------------------------------------:|:--------------------------------:| | dsp1.data.rom | DSP1 co-processor firmware | 3d81b45fa0c2aa8b852dfb1ece7c0971 | | dsp1.program.rom | DSP1 co-processor firmware | ae209fbe789fbf11a48aea5ab1197321 | | dsp1b.data.rom | DSP1B co-processor firmware | 1e3f568634a7d8284020dddc0ae905bc | | dsp1b.program.rom | DSP1B co-processor firmware | d10f446888e097cbf500f3f663cf4f6d | | dsp2.data.rom | DSP2 co-processor firmware | e9417e29223b139c3c4b635a2a3b8744 | | dsp2.program.rom | DSP2 co-processor firmware | aa6e5922a3ed5ded54f24247c11143c5 | | dsp3.data.rom | DSP3 co-processor firmware | 0a81210c0a940b997dd9843281008ee6 | | dsp3.program.rom | DSP3 co-processor firmware | d99ca4562818d49cee1f242705bba6f8 | | dsp4.data.rom | DSP4 co-processor firmware | ee4990879eb68e3cbca239c5bc20303d | | dsp4.program.rom | DSP4 co-processor firmware | a151023b948b90ffc23a5b594bb6fef2 | | cx4.data.rom | CX4 co-processor firmware | 037ac4296b6b6a5c47c440188d3c72e3 | | st010.data.rom | ST010 co-processor firmware | 254d70762b6f59f99c27c395aba7d07d | | st010.program.rom | ST010 co-processor firmware | 1d70019179a59a566a0bb5d3f2845544 | | st011.data.rom | ST011 co-processor firmware | 10bd3f4aa949737ab9836512c35bcc29 | | st011.program.rom | ST011 co-processor firmware | 95222ebf1c0c2990bcf25db43743f032 | | st018.data.rom | ST018 co-processor firmware | 49c898b60d0f15e90d0ba780dd12f366 | | st018.program.rom | ST018 co-processor firmware | dda40ccd57390c96e49d30a041f9a9e7 | | sgb.boot.rom | Super Game Boy BIOS | | ## Features Frontend-level settings or features that the bsnes-mercury Balanced core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | - | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✔ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The bsnes-mercury Balanced core's internal core name is 'bsnes-mercury' The bsnes-mercury Balanced core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.srm (Cartridge battery save) **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The bsnes-mercury Balanced core's core provided FPS is 60.0988118623 for NTSC games and 50.0069789082 for PAL games. - The bsnes-mercury Balanced core's core provided sample rate is 32040.5 Hz - The bsnes-mercury Balanced core's core provided aspect ratio is dependent on the ['Preferred aspect ratio' core option](#core-options). ## Super GameBoy !!! warning Super GameBoy support in this core is **Windows only**, and has **buggy save state support** and **visual glitches**. **Use the [higan Accuracy core](higan_accuracy.md#super-gameboy-support) or the [nSide Balanced core](nside_balanced.md#super-gameboy-support) for simplified, functional, and easily accessible Super Gameboy support.** For Super GameBoy support, you need sgb.boot.rom (in RetroArch's System directory), a GameBoy ROM and a Super GameBoy ROM. Please note that the Game Boy and Super GameBoy ROMs have to be unzipped. Super GameBoy is supported via the Subsystem API. There are two ways to access the Subsystem API. **One way is to access the Subsystem API through RetroArch's GUI like this.** First, we load our GameBoy ROM through 'Load Super GameBoy' in RetroArch's Main Menu. ![](../image/core/bsnes/menu1.png) ![](../image/core/bsnes/gb.png) Next, we load our Super GameBoy ROM through 'Load Super GameBoy' in RetroArch's Menu Menu. ![](../image/core/bsnes/menu2.png) ![](../image/core/bsnes/sgb.png) Then, we start the content by selecting 'Start GameBoy' In RetroArch's Menu Menu. ![](../image/core/bsnes/start.png) **The other way is to launch RetroArch with commandline like this.** ``` retroarch -L {path to bsnes core} {path to Super GameBoy ROM} --subsystem sgb {path to GameBoy rom} ``` ## MSU-1 !!! attention MSU-1 support in this core is complex. **Use the [Snes9x core](snes9x.md#msu-1-support) for simplified and easily accessible MSU-1 support.** MSU-1 support can be used by loading a correct .bml file. There's documentation for loading MSU-1 games in standalone higan [here](https://higan.readthedocs.io/en/stable/guides/import/#msu-1-games). ## Core options The bsnes-mercury Balanced core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Allow settings to reduce accuracy** [bsnes_violate_accuracy] (**disabled**|enabled) Respect accuracy-impacting settings. - **Special chip accuracy** [bsnes_chip_hle] (**LLE**|HLE) **The Allow settings to reduce accuracy core option must be enabled in order for this to function properly. ** Choose whether to use LLE (real BIOS) or HLE (emulated BIOS) for enhancement chips. HLE is less accurate but also less demanding for the special chips. The ST-0011 and ST-0018 co-processors cannot be HLE'd. - **SuperFX speed** [bsnes_superfx_overclock] (**100%**|150%|200%|300%|400%|500%|1000%) **The Allow settings to reduce accuracy core option must be enabled in order for this to function properly.** Overclock the [SuperFX chip](https://en.wikipedia.org/wiki/Super_FX). 100% is stock clockspeed. - **System region** [bsnes_region] (**auto**|ntsc|pal) Choose which region the system is from. - **Preferred aspect ratio** [bsnes_aspect_ratio] (**auto**|ntsc|pal) Choose the preferred aspect ratio. RetroArch's aspect ratio must be set to Core provided in the Video settings. - **Crop overscan** [bsnes_crop_overscan] (**disabled**|enabled) Crop out the potentially random glitchy video output that would have been hidden by the bezel around the edge of a standard-definition television screen. - **Gamma ramp (requires restart)** [bsnes_gamma_ramp] (**disabled**|enabled) Simulates the way a console’s display device differs from modern computer monitor’s colour reproduction. In particular, it simulates the slightly-different gamma correction used by the Super Famicom. ??? note "Gamma ramp - Disabled" ![](../image/core/higan/gamma_off.png) ??? note "Gamma ramp - Enabled" ![](../image/core/higan/gamma_on.png) ## Controllers The bsnes-mercury Balanced core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. - **[SNES Joypad](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller)** - Joypad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse ### User 2 device types - None - Doesn't disable input. - **[SNES Joypad](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller)** - Joypad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse - [Multitap](http://nintendo.wikia.com/wiki/Super_Multitap) - Joypad - Allows for up to five players to play together in multitap games. - [SuperScope](https://en.wikipedia.org/wiki/Super_Scope) - Lightgun - [Justifier](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - [Justifiers](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - Two Justifiers are plugged in, for two-player Justifier games. ### Multitap support Activating multitap support in compatible games can be configured by switching to the [Multitap device type](#controllers) for User 2. ### Controller tables #### Joypad ![](../image/controller/snes.png) | User 1 - 5 Remap descriptors | RetroPad Inputs | |------------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Y | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | X | ![](../image/retropad/retro_x.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | #### Mouse | RetroMouse Inputs | SNES Mouse | |-------------------------------------------------------|---------------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | SNES Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | SNES Mouse Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | SNES Mouse Right Button | #### Lightgun | RetroLightgun Inputs | SuperScope | Justifier(s) | |--------------------------------------------------------|---------------------------|---------------------| | ![](../image/retromouse/retro_mouse.png) Gun Crosshair | SuperScope Crosshair | Justifier Crosshair | | Gun Trigger | SuperScope Trigger | Justifier Trigger | | Gun Aux A | SuperScope Cursor | | | Gun Aux B | SuperScope Turbo | | | Gun Start | SuperScope Pause | Justifier Start | ## Compatibility | Game | Issue | |--------------------------|--------------------------------------------------------------------------------| | A.S.P. Air Strike Patrol | Black lines show up during gameplay. The shadow below the aircraft is missing. | ## External Links - [Official higan Website](https://byuu.org/) - [Official higan Upstream Downloads](https://byuu.org/emulation/higan/) - [Libretro bsnes-mercury Balanced Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/bsnes_mercury_balanced_libretro.info) - [Libretro bsnes-mercury Balanced Github Repository](https://github.com/libretro/bsnes-mercury) - [Report Libretro bsnes-mercury Balanced Core Issues Here](https://github.com/libretro/bsnes-mercury/issues) ### See also #### Nintendo - Sufami Turbo - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-jg)](bsnes-jg.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) #### Nintendo - Super Nintendo Entertainment System (+ Hacks) - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-jg)](bsnes-jg.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (higan Accuracy)](higan_accuracy.md) - [Nintendo - SNES / Famicom (nSide Balanced)](nside_balanced.md) - [Nintendo - SNES / Famicom (Mesen-S)](mesen-s.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) ================================================ FILE: docs/library/bsnes_mercury_performance.md ================================================ # Nintendo - SNES / Famicom (bsnes-mercury Performance) ## Background bsnes-mercury is a fork of higan, aiming to restore some useful features that have been removed, as well as improving performance a bit. Maximum accuracy is still uncompromising; anything that affects accuracy is optional and off by default. This core has been compiled with the Performance profile. Improvements include: * Improved framerate * Faster ROM loading * HLE emulation of some special chips is optionally restored (defaults to LLE), to improve performance and reduce reliance on those chip ROMs (they're not really easy to find). Chips for which no HLE emulation was developed (ST-0011 and ST-0018) are still LLE. * SuperFX overclock is now available (off by default, of course); if enabled, it makes SuperFX look quite a lot smoother. **The bsnes-mercury cores are not less accurate at default settings than the mainline bsnes cores (you have to explicitly enable 2 core options to switch to the less accurate special chip HLE).** ### Author/License The bsnes-mercury Performance core has been authored by - byuu - Alcaro The bsnes-mercury Performance core is licensed under - [GPLv3](https://github.com/libretro/bsnes-mercury/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the bsnes-mercury Performance core have the following file extensions: - .sfc - .smc - .bml ## Databases RetroArch database(s) that are associated with the bsnes-mercury Performance core: - [Nintendo - Super Nintendo Entertainment System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System.rdb) - [Nintendo - Super Nintendo Entertainment System Hacks](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System%20Hacks.rdb) - [Nintendo - Sufami Turbo](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Sufami%20Turbo.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:-----------------:|:--------------------------------------:|:--------------------------------:| | dsp1.data.rom | DSP1 co-processor firmware | 3d81b45fa0c2aa8b852dfb1ece7c0971 | | dsp1.program.rom | DSP1 co-processor firmware | ae209fbe789fbf11a48aea5ab1197321 | | dsp1b.data.rom | DSP1B co-processor firmware | 1e3f568634a7d8284020dddc0ae905bc | | dsp1b.program.rom | DSP1B co-processor firmware | d10f446888e097cbf500f3f663cf4f6d | | dsp2.data.rom | DSP2 co-processor firmware | e9417e29223b139c3c4b635a2a3b8744 | | dsp2.program.rom | DSP2 co-processor firmware | aa6e5922a3ed5ded54f24247c11143c5 | | dsp3.data.rom | DSP3 co-processor firmware | 0a81210c0a940b997dd9843281008ee6 | | dsp3.program.rom | DSP3 co-processor firmware | d99ca4562818d49cee1f242705bba6f8 | | dsp4.data.rom | DSP4 co-processor firmware | ee4990879eb68e3cbca239c5bc20303d | | dsp4.program.rom | DSP4 co-processor firmware | a151023b948b90ffc23a5b594bb6fef2 | | cx4.data.rom | CX4 co-processor firmware | 037ac4296b6b6a5c47c440188d3c72e3 | | st010.data.rom | ST010 co-processor firmware | 254d70762b6f59f99c27c395aba7d07d | | st010.program.rom | ST010 co-processor firmware | 1d70019179a59a566a0bb5d3f2845544 | | st011.data.rom | ST011 co-processor firmware | 10bd3f4aa949737ab9836512c35bcc29 | | st011.program.rom | ST011 co-processor firmware | 95222ebf1c0c2990bcf25db43743f032 | | st018.data.rom | ST018 co-processor firmware | 49c898b60d0f15e90d0ba780dd12f366 | | st018.program.rom | ST018 co-processor firmware | dda40ccd57390c96e49d30a041f9a9e7 | | sgb.boot.rom | Super Game Boy BIOS | | ## Features Frontend-level settings or features that the bsnes-mercury Performance core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | - | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✔ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The bsnes-mercury Performance core's internal core name is 'bsnes-mercury' The bsnes-mercury Performance core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.srm (Cartridge battery save) **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The bsnes-mercury Performance core's core provided FPS is 60.0988118623 for NTSC games and 50.0069789082 for PAL games. - The bsnes-mercury Performance core's core provided sample rate is 32040.5 Hz - The bsnes-mercury Performance core's core provided aspect ratio is dependent on the ['Preferred aspect ratio' core option](#core-options). ## Super GameBoy !!! warning Super GameBoy support in this core is **Windows only**, and has **buggy save state support** and **visual glitches**. **Use the [higan Accuracy core](higan_accuracy.md#super-gameboy-support) or the [nSide Balanced core](nside_balanced.md#super-gameboy-support) for simplified, functional, and easily accessible Super Gameboy support.** For Super GameBoy support, you need sgb.boot.rom (in RetroArch's System directory), a GameBoy ROM and a Super GameBoy ROM. Please note that the Game Boy and Super GameBoy ROMs have to be unzipped. Super GameBoy is supported via the Subsystem API. There are two ways to access the Subsystem API. **One way is to access the Subsystem API through RetroArch's GUI like this.** First, we load our GameBoy ROM through 'Load Super GameBoy' in RetroArch's Main Menu. ![](../image/core/bsnes/menu1.png) ![](../image/core/bsnes/gb.png) Next, we load our Super GameBoy ROM through 'Load Super GameBoy' in RetroArch's Menu Menu. ![](../image/core/bsnes/menu2.png) ![](../image/core/bsnes/sgb.png) Then, we start the content by selecting 'Start GameBoy' In RetroArch's Menu Menu. ![](../image/core/bsnes/start.png) **The other way is to launch RetroArch with commandline like this.** ``` retroarch -L {path to bsnes core} {path to Super GameBoy ROM} --subsystem sgb {path to GameBoy rom} ``` ## MSU-1 !!! attention MSU-1 support in this core is complex. **Use the [Snes9x core](snes9x.md#msu-1-support) for simplified and easily accessible MSU-1 support.** MSU-1 support can be used by loading a correct .bml file. There's documentation for loading MSU-1 games in standalone higan [here](https://higan.readthedocs.io/en/stable/guides/import/#msu-1-games). ## Core options The bsnes-mercury Performance core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Allow settings to reduce accuracy** [bsnes_violate_accuracy] (**disabled**|enabled) Respect accuracy-impacting settings. - **Special chip accuracy** [bsnes_chip_hle] (**LLE**|HLE) **The Allow settings to reduce accuracy core option must be enabled in order for this to function properly. ** Choose whether to use LLE (real BIOS) or HLE (emulated BIOS) for enhancement chips. HLE is less accurate but also less demanding for the special chips. The ST-0011 and ST-0018 co-processors cannot be HLE'd. - **SuperFX speed** [bsnes_superfx_overclock] (**100%**|150%|200%|300%|400%|500%|1000%) **The Allow settings to reduce accuracy core option must be enabled in order for this to function properly.** Overclock the [SuperFX chip](https://en.wikipedia.org/wiki/Super_FX). 100% is stock clockspeed. - **System region** [bsnes_region] (**auto**|ntsc|pal) Choose which region the system is from. - **Preferred aspect ratio** [bsnes_aspect_ratio] (**auto**|ntsc|pal) Choose the preferred aspect ratio. RetroArch's aspect ratio must be set to Core provided in the Video settings. - **Crop overscan** [bsnes_crop_overscan] (**disabled**|enabled) Crop out the potentially random glitchy video output that would have been hidden by the bezel around the edge of a standard-definition television screen. - **Gamma ramp (requires restart)** [bsnes_gamma_ramp] (**disabled**|enabled) Simulates the way a console’s display device differs from modern computer monitor’s colour reproduction. In particular, it simulates the slightly-different gamma correction used by the Super Famicom. ??? note "Gamma ramp - Disabled" ![](../image/core/higan/gamma_off.png) ??? note "Gamma ramp - Enabled" ![](../image/core/higan/gamma_on.png) ## Controllers The bsnes-mercury Performance core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. - **[SNES Joypad](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller)** - Joypad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse ### User 2 device types - None - Doesn't disable input. - **[SNES Joypad](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller)** - Joypad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse - [Multitap](http://nintendo.wikia.com/wiki/Super_Multitap) - Joypad - Allows for up to five players to play together in multitap games. - [SuperScope](https://en.wikipedia.org/wiki/Super_Scope) - Lightgun - [Justifier](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - [Justifiers](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - Two Justifiers are plugged in, for two-player Justifier games. ### Multitap support Activating multitap support in compatible games can be configured by switching to the [Multitap device type](#controllers) for User 2. ### Controller tables #### Joypad ![](../image/controller/snes.png) | User 1 - 5 Remap descriptors | RetroPad Inputs | |------------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Y | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | X | ![](../image/retropad/retro_x.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | #### Mouse | RetroMouse Inputs | SNES Mouse | |-------------------------------------------------------|---------------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | SNES Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | SNES Mouse Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | SNES Mouse Right Button | #### Lightgun | RetroLightgun Inputs | SuperScope | Justifier(s) | |--------------------------------------------------------|---------------------------|---------------------| | ![](../image/retromouse/retro_mouse.png) Gun Crosshair | SuperScope Crosshair | Justifier Crosshair | | Gun Trigger | SuperScope Trigger | Justifier Trigger | | Gun Aux A | SuperScope Cursor | | | Gun Aux B | SuperScope Turbo | | | Gun Start | SuperScope Pause | Justifier Start | ## Compatibility | Game | Issue | |--------------------------------------------------|--------------------------------------------------------------------------------| | A.S.P. Air Strike Patrol | Black lines show up during gameplay. The shadow below the aircraft is missing. | | Funaki Masakatsu Hybrid Wrestler – Tougi Denshou | Corrupted graphics on the Pancrase logo screen. | | Mecarobot Golf | The ground "wobbles" during gameplay. | | Mega Man X2 | Only displays a black screen. | | Mega Man X3 | Only displays a black screen. | | Mortal Kombat II | Various glitched graphics. | | NHL ’94 | Corrupted line on the NHL logo screen. | | Tetris Attack | Lots of flickering on the VS. CPU mode map screen. | ## External Links - [Official higan Website](https://byuu.org/) - [Official higan Upstream Downloads](https://byuu.org/emulation/higan/) - [Libretro bsnes-mercury Performance Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/bsnes_mercury_performance_libretro.info) - [Libretro bsnes-mercury Performance Github Repository](https://github.com/libretro/bsnes-mercury) - [Report Libretro bsnes-mercury Performance Core Issues Here](https://github.com/libretro/bsnes-mercury/issues) ### See also #### Nintendo - Sufami Turbo - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-jg)](bsnes-jg.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) #### Nintendo - Super Nintendo Entertainment System (+ Hacks) - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-jg)](bsnes-jg.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (higan Accuracy)](higan_accuracy.md) - [Nintendo - SNES / Famicom (nSide Balanced)](nside_balanced.md) - [Nintendo - SNES / Famicom (Mesen-S)](mesen-s.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) ================================================ FILE: docs/library/bsnes_performance.md ================================================ # Nintendo - SNES / Famicom (bsnes Performance) ## Background bsnes is a Super Nintendo emulator that began development on 2004-10-14. It focuses on accuracy and clean code above all else. It never uses speed or compatibility hacks. As a result, the minimum system requirements are greater than with other emulators. bsnes comes in three different profiles (accuracy, balanced and performance) which contain minor differences in the PPU (graphics) emulation. This core has been compiled with the Performance profile. Highly accurate SNES emulation. Whether to use the Accuracy, or Balanced or Performance core depends on how much accuracy you want to give up for game performance. Please check the [compatibility section](#compatibility) for more information. ### Author/License The bsnes Performance core has been authored by - byuu The bsnes Performance core is licensed under - [GPLv3](https://github.com/libretro/bsnes-libretro/blob/libretro/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the bsnes Performance core have the following file extensions: - .sfc - .smc - .bml ## Databases RetroArch database(s) that are associated with the bsnes Performance core: - [Nintendo - Super Nintendo Entertainment System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System.rdb) - [Nintendo - Super Nintendo Entertainment System Hacks](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System%20Hacks.rdb) - [Nintendo - Sufami Turbo](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Sufami%20Turbo.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. !!! attention The bsnes Performance core uses split ROMS for [special chip games](https://en.wikipedia.org/wiki/List_of_Super_NES_enhancement_chips#List_of_Super_NES_games_that_use_enhancement_chips). Notable DSP1/DSP1B Games: - Super Mario Kart - Pilotwings Notable DSP2 Games: - Dungeon Master Notable DSP3 Games: - SD Gundam GX Notable DSP4 Games: - Top Gear 3000 Notable Cx4 Games: - Mega Man X2 - Mega Man X3 | Filename | Description | md5sum | |:-----------------:|:--------------------------------------:|:--------------------------------:| | dsp1.data.rom | DSP1 co-processor firmware | 3d81b45fa0c2aa8b852dfb1ece7c0971 | | dsp1.program.rom | DSP1 co-processor firmware | ae209fbe789fbf11a48aea5ab1197321 | | dsp1b.data.rom | DSP1B co-processor firmware | 1e3f568634a7d8284020dddc0ae905bc | | dsp1b.program.rom | DSP1B co-processor firmware | d10f446888e097cbf500f3f663cf4f6d | | dsp2.data.rom | DSP2 co-processor firmware | e9417e29223b139c3c4b635a2a3b8744 | | dsp2.program.rom | DSP2 co-processor firmware | aa6e5922a3ed5ded54f24247c11143c5 | | dsp3.data.rom | DSP3 co-processor firmware | 0a81210c0a940b997dd9843281008ee6 | | dsp3.program.rom | DSP3 co-processor firmware | d99ca4562818d49cee1f242705bba6f8 | | dsp4.data.rom | DSP4 co-processor firmware | ee4990879eb68e3cbca239c5bc20303d | | dsp4.program.rom | DSP4 co-processor firmware | a151023b948b90ffc23a5b594bb6fef2 | | cx4.data.rom | CX4 co-processor firmware | 037ac4296b6b6a5c47c440188d3c72e3 | | st010.data.rom | ST010 co-processor firmware | 254d70762b6f59f99c27c395aba7d07d | | st010.program.rom | ST010 co-processor firmware | 1d70019179a59a566a0bb5d3f2845544 | | st011.data.rom | ST011 co-processor firmware | 10bd3f4aa949737ab9836512c35bcc29 | | st011.program.rom | ST011 co-processor firmware | 95222ebf1c0c2990bcf25db43743f032 | | st018.data.rom | ST018 co-processor firmware | 49c898b60d0f15e90d0ba780dd12f366 | | st018.program.rom | ST018 co-processor firmware | dda40ccd57390c96e49d30a041f9a9e7 | | sgb.boot.rom | Super Game Boy BIOS | | ## Features Frontend-level settings or features that the bsnes Performance core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | - | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✔ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✔ | | LEDs | ✕ | ### Directories The bsnes Performance core's internal core name is 'bsnes' The bsnes Performance core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.srm (Cartridge battery save) **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The bsnes Performance core's core provided FPS is 60.0988118623 for NTSC games and 50.0069789082 for PAL games. - The bsnes Performance core's core provided sample rate is 32040.5 Hz - The bsnes Performance core's core provided aspect ratio is 4/3 ## Super GameBoy !!! warning Super GameBoy support in this core is **Windows only**, and has **buggy save state support** and **visual glitches**. **Use the [higan Accuracy core](higan_accuracy.md#super-gameboy-support) or the [nSide Balanced core](nside_balanced.md#super-gameboy-support) for simplified, functional, and easily accessible Super Gameboy support.** For Super GameBoy support, you need sgb.boot.rom (in RetroArch's System directory), a GameBoy ROM and a Super GameBoy ROM. Please note that the Game Boy and Super GameBoy ROMs have to be unzipped. Super GameBoy is supported via the Subsystem API. There are two ways to access the Subsystem API. **One way is to access the Subsystem API through RetroArch's GUI like this.** First, we load our GameBoy ROM through 'Load Super GameBoy' in RetroArch's Main Menu. ![](../image/core/bsnes/menu1.png) ![](../image/core/bsnes/gb.png) Next, we load our Super GameBoy ROM through 'Load Super GameBoy' in RetroArch's Menu Menu. ![](../image/core/bsnes/menu2.png) ![](../image/core/bsnes/sgb.png) Then, we start the content by selecting 'Start GameBoy' In RetroArch's Menu Menu. ![](../image/core/bsnes/start.png) **The other way is to launch RetroArch with commandline like this.** ``` retroarch -L {path to bsnes core} {path to Super GameBoy ROM} --subsystem sgb {path to GameBoy rom} ``` ## MSU-1 !!! attention MSU-1 support in this core is complex. **Use the [Snes9x core](snes9x.md#msu-1-support) for simplified and easily accessible MSU-1 support.** MSU-1 support can be used by loading a correct .bml file. There's documentation for loading MSU-1 games in standalone higan [here](https://higan.readthedocs.io/en/stable/guides/import/#msu-1-games). ## Controllers The bsnes Performance core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Disables input. - **[SNES Joypad](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller)** - Joypad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse ### User 2 device types - None - Disables input. - **[SNES Joypad](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller)** - Joypad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse - [Multitap](http://nintendo.wikia.com/wiki/Super_Multitap) - Joypad - Allows for up to five players to play together in multitap games. - [SuperScope](https://en.wikipedia.org/wiki/Super_Scope) - Lightgun - [Justifier](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - [Justifiers](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - Two Justifiers are plugged in, for two-player Justifier games. ### Multitap support Activating multitap support in compatible games can be configured by switching to the [Multitap device type](#controllers) for User 2. ### Controller tables #### Joypad ![](../image/controller/snes.png) | User 1 - 5 Remap descriptors | RetroPad Inputs | |------------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Y | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | X | ![](../image/retropad/retro_x.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | #### Mouse | RetroMouse Inputs | SNES Mouse | |-------------------------------------------------------|---------------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | SNES Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | SNES Mouse Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | SNES Mouse Right Button | #### Lightgun | RetroLightgun Inputs | SuperScope | Justifier(s) | |--------------------------------------------------------|----------------------|---------------------| | ![](../image/retromouse/retro_mouse.png) Gun Crosshair | SuperScope Crosshair | Justifier Crosshair | | Gun Trigger | SuperScope Trigger | Justifier Trigger | | Gun Aux A | SuperScope Cursor | | | Gun Aux B | SuperScope Turbo | | | Gun Start | SuperScope Pause | Justifier Start | ## Compatibility | Game | Issue | |--------------------------------------------------|--------------------------------------------------------------------------------| | A.S.P. Air Strike Patrol | Black lines show up during gameplay. The shadow below the aircraft is missing. | | Funaki Masakatsu Hybrid Wrestler – Tougi Denshou | Corrupted graphics on the Pancrase logo screen. | | Mecarobot Golf | The ground "wobbles" during gameplay. | | Mega Man X2 | Only displays a black screen. | | Mega Man X3 | Only displays a black screen. | | Mortal Kombat II | Various glitched graphics. | | NHL ’94 | Corrupted line on the NHL logo screen. | | Tetris Attack | Lots of flickering on the VS. CPU mode map screen. | ## External Links - [Official higan Website](https://byuu.org/) - [Official higan Upstream Downloads](https://byuu.org/emulation/higan/) - [Libretro bsnes Performance Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/bsnes_performance_libretro.info) - [Libretro bsnes Performance Github Repository](https://github.com/libretro/bsnes-libretro) - [Report Libretro bsnes Performance Core Issues Here](https://github.com/libretro/bsnes-libretro/issues) ### See also #### Nintendo - Sufami Turbo - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-jg)](bsnes-jg.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) #### Nintendo - Super Nintendo Entertainment System (+ Hacks) - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-jg)](bsnes-jg.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (higan Accuracy)](higan_accuracy.md) - [Nintendo - SNES / Famicom (nSide Balanced)](nside_balanced.md) - [Nintendo - SNES / Famicom (Mesen-S)](mesen-s.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) ================================================ FILE: docs/library/cannonball.md ================================================ # Cannonball ## Background This is an OutRun game engine recreation written by Chris White in 2014. It has been ported to the libretro API. The Cannonball core has been authored by - Chris White The Cannonball core is licensed under - [Non-commercial](https://github.com/libretro/cannonball/blob/master/docs/license.txt) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## How to start the Cannonball core: - To start the Cannonball core, you need to obtain Cannonball's data files. You can do this by going to RetroArch's main menu screen and selecting 'Online Updater'. From there, select 'Content Downloader'. - Select 'Cannonball', then select 'CannonBall.zip'. This should download and extract this file to RetroArch's Downloads directory. - Next, follow this [guide](https://github.com/djyt/cannonball/blob/master/roms/roms.txt) and place OutRun Revision B ROMs in the CannonBall directory. - Below is a pictured example of a working Cannonball setup. ![](../image/core/cb/cb.png) - Go back to RetroArch's main menu screen. Select 'Load Content', then 'Downloads'. - Select the 'CannonBall' directory, then select 'CannonBall.game'. - If you are asked which core to select, choose 'Cannonball'. The content should now start running! ## Extensions Content that can be loaded by the Cannonball core have the following file extensions: - .game - .88 RetroArch database(s) that are associated with the Cannonball core: - [Cannonball](https://github.com/libretro/libretro-database/blob/master/rdb/Cannonball.rdb) ## Features - Smoother 60fps gameplay - [True Widescreen Play Mode](https://youtube.com/clip/UgkxU6mqSPJX9ZAiAyd8N0oXCmHk8rRVHTdS) - Force Feedback support - Custom Track support from [LayOut](https://github.com/djyt/layout/wiki) - New Game Modes (Continuous Mode & Time Trial Mode) - [Many, many more enhancements](https://github.com/djyt/cannonball/wiki/Cannonball-Manual#enhancements) Frontend-level settings or features that the Cannonball core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✕ | | Saves | ✔ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Directories The Cannonball core's library name is 'Cannonball' The Cannonball core saves/loads to/from these directories. **Frontend's Home directory** | File | Description | |:------------:|:-------------:| | config.xml | Config File | | hiscores.xml | Hiscores File | ## Geometry and timing - The Cannonball core's core provided FPS is 60 when the [Video Framerate core option](#core-options) is set to Smooth (60) or Original (60/30) - The Cannonball core's core provided FPS is 120 when the [Video Framerate core option](#core-options) is set to Ultra Smooth (120) - The Cannonball core's core provided FPS is 30 when the [Video Framerate core option](#core-options) is set to Low (30) - The Cannonball core's core provided sample rate is 44040 Hz when the [Video Framerate core option](#core-options) is set to Ultra Smooth (120) - The Cannonball core's core provided sample rate is 44100 Hz when the [Video Framerate core option](#core-options) is not set to Ultra Smooth (120) - The Cannonball core's base width is 320 - The Cannonball core's base height is 224 - The Cannonball core's max width is 640 - The Cannonball core's max height is 448 - The Cannonball core's core provided aspect ratio is 4/3 when the [Video Widescreen Mode core option](#core-options) is set to Off - The Cannonball core's core provided aspect ratio is 16/9 when the [Video Widescreen Mode core option](#core-options) is set to On ## Core options The Cannonball core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Menu At Start** [cannonball_menu_enabled] (**ON**|OFF) When enabled; the Cannonball core shows the main menu upon startup. When disabled; the Cannonball core goes into attract mode upon startup. - **Menu Road Scroll Speed** [cannonball_menu_road_scroll_speed] (**50**|60|70|80|90|100|150|200|300|400|500|5|10|15|20|25|30|40) Use this to configure the speed at which the road on the Main Menu scrolls at. - **Video Widescreen Mode** [cannonball_video_widescreen] (**ON**|OFF) Explained [here](https://github.com/djyt/cannonball/wiki/Cannonball-Manual#video-modes). - **Video High-Resolution Mode** [cannonball_video_hires] (**OFF**|ON) The original game ran at 320x224. This mode doubles that resolution to 640x448. However, rather than simply doubling up the display, the sprites and road are rendered at a higher resolution where possible. - **Video Framerate** [cannonball_video_fps] (**Smooth (60)**|Ultra Smooth (120)|Original (60/30)) Explained [here](https://github.com/djyt/cannonball/wiki/Cannonball-Manual#video-modes). - **Advertise Sound** [cannonball_sound_advertise] (**ON**|OFF) Play sounds in attract mode. - **Preview Music** [cannonball_sound_preview] (**ON**|OFF) Preview the music tracks at the point of selection in-game. The original game did not have this option and you would not hear the audio track until the game started. - **Fix Samples (use opr-10188.71f)** [cannonball_sound_fix_samples] (**ON**|OFF) Explained [here](https://github.com/djyt/cannonball/wiki/Cannonball-Manual#fix-corrupted-audio). - **Gear Mode** [cannonball_gear] (**Manual**|Manual Cabinet|Manual 2 Buttons|Automatic) Change the gear shift behaviour. Useful to configure based on your target hardware. 0 = Manual (Click to shift, for normal play) 1 = Manual (Hold to shift, for cabinet play) 2 = Manual (Separate Buttons for High/Low) 3 = Automatic (No need to change gear) - **Analog Controls (off to allow digital speed setup)** [cannonball_analog] (**ON**|OFF) Self-explanatory. - **Digital Steer Speed** [cannonball_steer_speed] (**3**|4|5|6|7|8|9|1|2) Awaiting description. - **Digital Pedal Speed** [cannonball_pedal_speed] (**4**|5|6|7|8|9|1|2|3) Awaiting description. - **Time** [cannonball_dip_time] (**Easy (80s)**|Normal (75s)|Hard (72s)|Very Hard (70s)|Infinite Time) Explained [here](https://github.com/djyt/cannonball/wiki/Cannonball-Manual#outrun-engine-settings). - **Traffic** [cannonball_dip_traffic] (**Normal**|Hard|Very Hard|No Traffic|Easy) Explained [here](https://github.com/djyt/cannonball/wiki/Cannonball-Manual#outrun-engine-settings). - **Freeplay Mode** [cannonball_freeplay] (**OFF**|ON) Awaiting description. - **Use Japanese Tracks Version** [cannonball_jap] (**OFF**|ON) Explained [here](https://github.com/djyt/cannonball/wiki/Cannonball-Manual#japanese-courses) - **Use Prototype Stage 1** [cannonball_prototype] (**OFF**|ON) Explained [here](https://github.com/djyt/cannonball/wiki/Cannonball-Manual#prototype-coconut-beach). - **Objects Limit Enhanced** [cannonball_level_objects] (**ON**|OFF) Explained [here](https://github.com/djyt/cannonball/wiki/Cannonball-Manual#outrun-engine-settings) - **Original Traffic Patterns Randomization** [cannonball_randomgen] (**ON**|OFF) Awaiting description. - **Force AI To Play** [cannonball_force_ai] (**OFF**|ON) Awaiting description. - **Fix Original Game Bugs** [cannonball_fix_bugs] (**ON**|OFF) Explained [here](https://github.com/djyt/cannonball/wiki/Cannonball-Manual#bug-fixes) - **Fix Timing Bugs** [cannonball_fix_timer] (**OFF**|ON) Awaiting description. - **Display Debug Info For LayOut** [cannonball_layout_debug] (**OFF**|ON) Awaiting description. - **New Attract** [cannonball_new_attract] (**ON**|OFF) Explained [here](https://github.com/djyt/cannonball/wiki/Cannonball-Manual#outrun-engine-settings). - **Time Trial Laps** [cannonball_ttrial_laps] (**3**|4|5|1|2) Awaiting description. - **Time Trial Traffic Amount** [cannonball_ttrial_traffic] (**3**|4|5|6|7|8|0|1|2) Awaiting description. - **Continuous Mode Traffic Amount** [cannonball_cont_traffic] (**3**|4|5|6|7|8|0|1|2) Awaiting description. ## Joypad | RetroPad Inputs | User 1 input descriptors | |------------------------------------------------|--------------------------| | ![](../image/retropad/retro_b.png) | Accelerate | | ![](../image/retropad/retro_y.png) | Brake | | ![](../image/retropad/retro_select.png) | Coin | | ![](../image/retropad/retro_start.png) | Start | | ![](../image/retropad/retro_dpad_up.png) | Up | | ![](../image/retropad/retro_dpad_down.png) | Down | | ![](../image/retropad/retro_dpad_left.png) | Left | | ![](../image/retropad/retro_dpad_right.png) | Right | | ![](../image/retropad/retro_a.png) | Gear | | ![](../image/retropad/retro_x.png) | Gear | | ![](../image/retropad/retro_l1.png) | Adjust View | | ![](../image/retropad/retro_r1.png) | Go Back To Menu | | ![](../image/retropad/retro_left_stick.png) X | Analog X | | ![](../image/retropad/retro_left_stick.png) Y | Analog Y | ## External Links - [Official Cannoball Github Wiki](https://github.com/djyt/cannonball/wiki) - [Official Cannonball Github Repository](https://github.com/djyt/cannonball) - [Libretro Cannonball Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/cannonball_libretro.info) - [Libretro Cannonball Github Repository](https://github.com/libretro/cannonball) - [Report Libretro Cannonball Core Issues Here](https://github.com/libretro/cannonball/issues) - [How to setup video](https://www.youtube.com/watch?v=ILGQqmpbg6E) ================================================ FILE: docs/library/caprice32.md ================================================ # Amstrad - CPC (Caprice32) ## Background Caprice32 is a software emulator of the Amstrad CPC 8bit home computer series running on Linux and Windows. The emulator faithfully imitates the CPC464, CPC664, CPC6128, CPC6128+ and GX4000 models. By recreating the operations of all hardware components at a low level, the emulator achieves a high degree of compatibility with original CPC software. These programs or games can be run unmodified at real-time or higher speeds, depending on the emulator host environment. ### Author/License The Caprice32 core has been authored by - Ulrich Doewich - David Colmenero (D_Skywalk) - Colin Pitrat The Caprice32 core is licensed under - [GPLv2](https://github.com/ColinPitrat/caprice32/blob/master/COPYING.txt) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Caprice32 core have the following file extensions: - .dsk - .sna - .tap - .cdt - .voc - .m3u - .cpr - .zip ## Databases RetroArch database(s) that are associated with the Caprice32 core: - [Amstrad - CPC](https://github.com/libretro/libretro-database/blob/master/rdb/Amstrad%20-%20CPC.rdb) (TOSEC) ## Features Frontend-level settings or features that the Caprice32 core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✔ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Caprice32 core's internal core name is 'cap32'. The Caprice32 core saves/loads to/from these directories. **Loaded content's directory** - 'content-name'#.SNA (SNA) ### Geometry and timing * The Caprice32 core's core provided FPS is 50 * The Caprice32 core's core provided sample rate is 44100 Hz * The Caprice32 core's core provided aspect ratio is 4/3 ## Usage The Caprice32 core has a virtual keyboard GUI that can be accessed through SELECT (configured by cap32_combokey) or F9. The mouse cursor can be controlled by RetroPad D-Pad and use button A to press a Key. ![](../image/core/caprice32/vkbd_v2.png) ## Core options The Caprice32 core has the following option(s) that can be tweaked from the core options menu. !!! tip Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. | Core option | Description | Default | | --- | --- | --- | | Autorun | If enabled, the core will run the first bas/bin found in the DSK. `cap32_autorun = "enabled|disabled"` | `enabled` | | Combo Key | See [Combo list](#combo-list) below. `cap32_combokey = "select|y|b|disabled"` | `select` | | Internal resolution | Self-explanatory. `cap32_resolution = "384x272|400x300"` | `384x272` | | Model (Restart) | Choose which Amstrad CPC model to emulate. `cap32_model = "6128|464|6128+"` | `6128` | | Ram size (Restart) | CPC physical RAM size in kB. `cap32_ram = "128|64|192|576"` | `128` | | Status Bar | Status bar configuration `cap32_statusbar = "onloading|enabled|disabled"` | `onloading` | | Floppy Sound | Disk emulated sound configuration `cap32_floppy_sound = "enabled|disabled"` | `enabled` | | Monitor Type | Choose between a color display or a monochrome display. `cap32_scr_tube = "color|green|white"` | `color` | | Monitor Intensity | Screen cathodic tube intensity. `cap32_scr_intensity = "5|6|7|8|9|10|11|12|13|14|15"` | `5` | | CPC Language (Restart) | Choose between english, french or spanish keyboard layout. `cap32_lang_layout = "english|french|spanish"` | `english` | | User 1 Joystick Configuration | Select Joy/Overlay configuration for player 1. `cap32_retrojoy0 = "joystick|qaop|incentive"` | `joystick` | | User 2 Joystick Configuration | Select Joy/Overlay configuration for player 2. `cap32_retrojoy1 = "joystick|qaop|incentive|joystick_port2"` | `joystick` | !!! note "cap32_scr_tube = color" ![](../image/core/caprice32/tube_off.png) !!! note "cap32_scr_tube = green" ![](../image/core/caprice32/tube_on.png) !!! attention These 'scr_intensity' core option screenshots have been taken with the 'cap32_scr_tube' core option set to 'color'. !!! note "scr_intensity = 5" ![](../image/core/caprice32/5.png) !!! note "scr_intensity = 15" ![](../image/core/caprice32/15.png) ## Controllers The Caprice32 core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 - 2 device types - None - Doesn't disable input. There's no reason to switch to this. - **RetroPad** - Joypad - Don't use this. Switch to Amstrad Joystick for joypad input. - Amstrad Joystick - Joypad - Use this for joypad input. - Amstrad Keyboard - Keyboard - Keyboard input are always active. Has keymapper support. ### Other controllers - Mouse - The mouse cursor in the Virtual Keyboard GUI can be controlled with mouse inputs. ### Controller tables using RetroPad device Type #### JOY CONFIG DEFAULT (JOYSTICK) | User 1 Remap descriptors | RetroPad Inputs | Amstrad Joystick | |--------------------------|------------------------------------------------|------------------------------| | B | ![](../image/retropad/retro_b.png) | FIRE1 | | Y | ![](../image/retropad/retro_y.png) | | | Start | ![](../image/retropad/retro_start.png) | | | Up | ![](../image/retropad/retro_dpad_up.png) | JOY UP | | Down | ![](../image/retropad/retro_dpad_down.png) | JOY DOWN | | Left | ![](../image/retropad/retro_dpad_left.png) | JOY LEFT | | Right | ![](../image/retropad/retro_dpad_right.png) | JOY RIGHT | | A | ![](../image/retropad/retro_a.png) | FIRE2 | | X | ![](../image/retropad/retro_x.png) | | | L | ![](../image/retropad/retro_l1.png) | CTRL | | R | ![](../image/retropad/retro_r1.png) | INTRO | | L2 | ![](../image/retropad/retro_l2.png) | F1 | | R2 | ![](../image/retropad/retro_r2.png) | F2 | | Select | ![](../image/retropad/retro_select.png) | COMBO (see bellow) | | L3 | ![](../image/retropad/retro_l3.png) | | | R3 | ![](../image/retropad/retro_r3.png) | | #### JOY CONFIG QAOP (GENERAL KEYB) | User 1 Remap descriptors | RetroPad Inputs | Amstrad Joystick | |--------------------------|------------------------------------------------|------------------------------| | B | ![](../image/retropad/retro_b.png) | B | | Y | ![](../image/retropad/retro_y.png) | Y | | Start | ![](../image/retropad/retro_start.png) | K *(to select Keyb in games)*| | Up | ![](../image/retropad/retro_dpad_up.png) | Q | | Down | ![](../image/retropad/retro_dpad_down.png) | A | | Left | ![](../image/retropad/retro_dpad_left.png) | O | | Right | ![](../image/retropad/retro_dpad_right.png) | P | | A | ![](../image/retropad/retro_a.png) | SPACE | | X | ![](../image/retropad/retro_x.png) | N | | L | ![](../image/retropad/retro_l1.png) | CTRL | | R | ![](../image/retropad/retro_r1.png) | INTRO | | L2 | ![](../image/retropad/retro_l2.png) | F1 | | R2 | ![](../image/retropad/retro_r2.png) | F2 | | Select | ![](../image/retropad/retro_select.png) | COMBO (see bellow) | | L3 | ![](../image/retropad/retro_l3.png) | | | R3 | ![](../image/retropad/retro_r3.png) | | #### JOY INCENTIVE ([INCENTIVE GAMES](https://en.wikipedia.org/wiki/Incentive_Software)) | User 1 Remap descriptors | RetroPad Inputs | Amstrad Joystick | |--------------------------|------------------------------------------------|-------------------| | B | ![](../image/retropad/retro_b.png) | SPACE | | Y | ![](../image/retropad/retro_y.png) | W | | Start | ![](../image/retropad/retro_start.png) | F | | Up | ![](../image/retropad/retro_dpad_up.png) | CURSOR UP | | Down | ![](../image/retropad/retro_dpad_down.png) | CURSOR DOWN | | Left | ![](../image/retropad/retro_dpad_left.png) | CURSOR LEFT | | Right | ![](../image/retropad/retro_dpad_right.png) | CURSOR RIGHT | | A | ![](../image/retropad/retro_a.png) | A | | X | ![](../image/retropad/retro_x.png) | C | | L | ![](../image/retropad/retro_l1.png) | P | | R | ![](../image/retropad/retro_r1.png) | L | | L2 | ![](../image/retropad/retro_l2.png) | R | | R2 | ![](../image/retropad/retro_r2.png) | U | | Select | ![](../image/retropad/retro_select.png) | COMBO (see bellow)| | L3 | ![](../image/retropad/retro_l3.png) | | | R3 | ![](../image/retropad/retro_r3.png) | | #### COMBO LIST If you press **SELECT** you could make a combo with other buttons: | Combo | RetroPad Inputs | Amstrad Writes | |----------------|------------------------------------------------------------------------------------------|------------------| | Select + B | ![](../image/retropad/retro_select.png) + ![](../image/retropad/retro_b.png) | CAT | | Select + Y | ![](../image/retropad/retro_select.png) + ![](../image/retropad/retro_y.png) | \|CPM | | Select + Start | ![](../image/retropad/retro_select.png) + ![](../image/retropad/retro_start.png) | SHOW V-KEYBOARD | | Select + Up | ![](../image/retropad/retro_select.png) + ![](../image/retropad/retro_dpad_up.png) | [1], [Y] | | Select + Down | ![](../image/retropad/retro_select.png) + ![](../image/retropad/retro_dpad_down.png) | [2], [N] | | Select + Left | ![](../image/retropad/retro_select.png) + ![](../image/retropad/retro_dpad_left.png) | [4], [S] | | Select + Right | ![](../image/retropad/retro_select.png) + ![](../image/retropad/retro_dpad_right.png) | [3], [J] | | Select + A | ![](../image/retropad/retro_select.png) + ![](../image/retropad/retro_a.png) | RUN"DISK RUN"DISC| | Select + X | ![](../image/retropad/retro_select.png) + ![](../image/retropad/retro_x.png) | \|TAPE RUN" | *This combos are useful to load games and select options in game-menus.* #### Keyboard This core allows **direct keyboard access**, you could use your keyboard as an original CPC. To achieve that you must activate the **[Game Focus](https://docs.libretro.com/guides/input-and-controls/#cores-with-direct-keyboard-input)**, by default the hotkey is configured to the **SCROLL_LOCK** key. ##### English layout ![](https://user-images.githubusercontent.com/560310/52812237-4c4fbd80-3097-11e9-8537-88f62e8ba5e8.png) ##### Spanish layout ![](https://user-images.githubusercontent.com/560310/54316295-9ff2ef80-45e0-11e9-9ae4-a2e3fb064600.png) ##### French layout ![](https://user-images.githubusercontent.com/560310/54316280-97021e00-45e0-11e9-91b5-da73a87534d6.png) #### Keyboard Binds | RetroKeyboard Special Inputs | Amstrad | |------------------------------|------------------------------| | Keyboard Keypad 0 | CPC_KEY_F0 | | Keyboard Keypad 1 | CPC_KEY_F1 | | Keyboard Keypad 2 | CPC_KEY_F2 | | Keyboard Keypad 3 | CPC_KEY_F3 | | Keyboard Keypad 4 | CPC_KEY_F4 | | Keyboard Keypad 5 | CPC_KEY_F5 | | Keyboard Keypad 6 | CPC_KEY_F6 | | Keyboard Keypad 7 | CPC_KEY_F7 | | Keyboard Keypad 8 | CPC_KEY_F8 | | Keyboard Keypad 9 | CPC_KEY_F9 | | Keyboard Keypad Period . | CPC_KEY_FDOT | | Keyboard Keypad Enter | CPC_KEY_SMALL_ENTER | | Keyboard Delete | CPC_KEY_CLR | | Keyboard Insert | CHANGE CURSOR/JOY EMULATION | | Keyboard Home | PLAY TAPE | | Keyboard End | STOP TAPE | | Keyboard Page Up | TAPE REWIND | | Keyboard Page Down | - | | Keyboard F9 | SHOW V-KEYBOARD | | Keyboard F10 | MAIN GUI | | Keyboard Right Alt | CPC_KEY_COPY | | Keyboard Left Alt | CPC_KEY_COPY | | Keyboard Right Shift | CPC_KEY_FIRE2 (JOY EMULATION)| | Keyboard Right Control | CPC_KEY_FIRE1 (JOY EMULATION)| Choose AMSTRAD KEYBOARD in Quick Menu > Controls to customize your **retropad keys per game**. #### Mouse | RetroMouse Inputs | Virtual Keyboard GUI Inputs | |-------------------------------------------------------|-----------------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | Mouse Left Button | ## M3U and Disk control When you have a multi disk game, you can use a m3u file to specify each disk of the game and change them from the RetroArch Disk control interface. A M3U file is a simple text file with one disk per line (see https://en.wikipedia.org/wiki/M3U). Example: **Alive (F).m3u** Alive (F) - Disk 1A.dsk Alive (F) - Disk 1B.dsk Path can be absolute or relative to the location of the M3U file. When a game ask for it, you can change the current disk in the RetroArch 'Disk Control' menu: * Eject the current disk with 'Disk Cycle Tray Status' * Select the right disk index * Insert the new disk with 'Disk Cycle Tray Status' ### Specify a specific command to launch a game If the autorun option of the core does a pretty good job to guess what command must be executed to launch a game on the CPC, there is some problems (cpm disk and strange catalogs for the most). You can specify a command to be executed on the CPC when the emu launch. All you have to do is to add a comment like this in the m3u file : ``` #COMMAND: ``` Even for one disk game, you can create a m3u file like this one : Jack the Nipper II... In Coconut Capers.m3u ``` #COMMAND:|CPM Jack the Nipper II... In Coconut Capers (E).dsk ``` ## External Links - [Official Caprice32 Github Repository](https://github.com/ColinPitrat/caprice32) - [Libretro Caprice32 Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/cap32_libretro.info) - [Libretro Caprice32 Github Repository](https://github.com/libretro/libretro-cap32) - [Report Libretro Caprice32 Core Issues Here](https://github.com/libretro/libretro-cap32/issues) ### See also #### Amstrad - CPC - [Amstrad - CPC (CrocoDS)](crocods.md) ================================================ FILE: docs/library/chailove.md ================================================ # ChaiLove ## Background [ChaiLove](https://github.com/libretro/libretro-chailove) is a framework for making 2D games with [ChaiScript](http://chaiscript.com/). ChaiLove games can be played with LibRetro/RetroArch through the ChaiLove core. #### How to start the ChaiLove core: - As an example showcasing loading content with Chailove core, we will load the [Floppy Bird](https://github.com/robloach/chailove-floppybird) game hosted on RetroArch's Content Downloader. You can do this by going to RetroArch's main menu screen and selecting 'Online Updater'. From there, select 'Content Downloader'.
![](../image/core/all/download.png)
- Select 'ChaiLove', then select 'Floppy Bird.chailove'. This should download and extract this file to RetroArch's Downloads directory.
![](../image/core/chailove/chailove.png)
- Go back to RetroArch's main menu screen. Select 'Load Content', then 'Downloads'.
![](../image/core/all/load.png)
![](../image/core/all/downloads.png)
- Select 'Floppy Bird.chailove'. - If you are asked which core to select, choose 'ChaiLove'. The content should now start running! ### Author/License The ChaiLove core has been authored by - Rob Loach The ChaiLove core is licensed under - [MIT](https://github.com/libretro/libretro-chailove/blob/master/LICENSE.md) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the ChaiLove core have the following file extensions: - `.chai` - `.chailove` ## Databases RetroArch database(s) that are associated with the ChaiLove core: - [ChaiLove](https://github.com/libretro/libretro-database/blob/master/rdb/ChaiLove.rdb) ## Features Frontend-level settings or features that the ChaiLove core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✕ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✔ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✔ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The ChaiLove core's internal core name is 'ChaiLove' The ChaiLove core saves/loads to/from these directories. **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The ChaiLove core's core provided FPS is 60 - The ChaiLove core's core provided sample rate is 44100 Hz - The ChaiLove core's core provided aspect ratio is game provided ## Core options The ChaiLove core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Alpha Blending** [chailove_alphablending] (**enabled**|disabled) Enable or disable alpha blending (transparency). ??? note "Alpha Blending - On" ![](../image/core/chailove/alpha_on.png) ??? note "Alpha Blending - Off" ![](../image/core/chailove/alpha_off.png) - **High Quality** [chailove_highquality] (**enabled**|disabled) Enable or disable extra visual features. ??? note "High Quality - On" ![](../image/core/chailove/quality_on.png) ??? note "High Quality - Off" ![](../image/core/chailove/quality_off.png) ## Controllers The ChaiLove core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 - 5 device types - None - Doesn't disable input. - **RetroPad** - Joypad - Stay on this. - RetroPad w/Analog - Joypad - There's no reason to switch to this. ### Controller tables #### Joypad !!! attention What the buttons do are game specific. | User 1 - 5 Remap descriptors | RetroPad Inputs | |------------------------------|------------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Y | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | X | ![](../image/retropad/retro_x.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | ## External Links - [ChaiScript Website](http://chaiscript.com/) - [ChaiLove API Documentation Website](https://rawgit.com/libretro/libretro-chailove/docs/) - [ChaiLove Github Wiki](https://github.com/libretro/libretro-chailove/wiki) - [Libretro ChaiLove Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/chailove_libretro.info) - [Libretro ChaiLove Github Repository](https://github.com/libretro/libretro-chailove) - [Report Libretro ChaiLove Core Issues Here](https://github.com/libretro/libretro-chailove/issues) - [Floppy Bird](https://github.com/robloach/chailove-floppybird) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0IfOE39vx0sftVugNnMgC67o) ### See also #### Custom Engine - [Lua Engine (Lutro)](lutro.md) ================================================ FILE: docs/library/citra.md ================================================ # Nintendo - 3DS (Citra) ## Background Citra is an experimental open-source Nintendo 3DS emulator/debugger written in C++. It is written with portability in mind. The Citra core has been authored by - Citra Emulation Project The Citra core is licensed under - [GPLv2](https://github.com/citra-emu/citra/blob/master/license.txt) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ### Requirements OpenGL 3.3 or higher ![](../image/core/citra/gl.png) !!! warning There is currently no ‘working’ macOS version available. This is because this core requires OpenGL core 3.3 context, and RetroArch on macOS currently does not support this. We will have to add support for this to a future version of RetroArch on macOS before this core will start to work on it. ## Decryption keys Citra requires [AES keys](https://citra-emu.org/wiki/aes-keys/) in order to load encrypted games. `aes_keys.txt` needs to be placed in ../saves/Citra/sysdata. ## Extensions Content that can be loaded by the Citra core have the following file extensions: - .3ds - .3dsx - .elf - .axf - .cci - .cxi - .app RetroArch database(s) that are associated with the Citra core: - [Nintendo - Nintendo 3DS](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%203DS.rdb) ## Features Frontend-level settings or features that the Citra core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✔ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Citra core's library name is 'Citra' The Citra core saves/loads to/from these directories. The Citra Shaders should be in ../saves/Citra/shaders/opengl/transferable **Frontend's Save directory** - [Citra System and Save files](https://citra-emu.org/wiki/user-directory/) ### Geometry and timing - The Citra core's core provided FPS is 60.0 - The Citra core's core provided sample rate is 32728 Hz - The Citra core's base width is (Base width) - The Citra core's base height is (Base height) - The Citra core's max width is (Max width) - The Citra core's max height is (Max height) - The Citra core's core provided aspect ratio is (Ratio) ## Cheats The Citra core supports internal cheats, but you have to enable them manually: 1. Grab a Citra cheats file for your game, you can find a lot of them here for example: [https://github.com/iSharingan/CTRPF-AR-CHEAT-CODES/tree/master/Cheats](https://github.com/iSharingan/CTRPF-AR-CHEAT-CODES/tree/master/Cheats) 2. Put the file (`[game_id].txt`) in your frontend's `saves/Citra/cheats/` folder. 3. Open the .txt file with a text editor, add `*citra_enabled` below the cheat title and save changes. As an example, if you want to enable the "All Characters" cheat for Mario Kart 7 you have to edit `[frontend_dir]/saves/Citra/cheats/0004000000030800.txt` and change that part: ``` [All Characters, Game v1.0] D3000000 14000000 0013C99C 01FF003F ``` to: ``` [All Characters, Game v1.0] *citra_enabled D3000000 14000000 0013C99C 01FF003F ``` ## Core options The Citra core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Enable CPU JIT** [citra_use_cpu_jit] (**enabled**|disabled) Enable Citra's 'dynarmic' dynamic recomplier. Can improve performance. Instructions that are not implemented by the recompiler fall back into the interpreter CPU core. If disabled, Citra will solely use the Interpreter CPU core. - **Enable hardware renderer** [citra_use_hw_renderer] (**enabled**|disabled) Awaiting description. - **Enable shader JIT** [citra_use_shader_jit] (**enabled**|disabled) Awaiting description. - **Enable hardware shaders** [citra_use_hw_shaders] (**enabled**|disabled) Awaiting description. - **Save hardware shader cache to disk** [citra_use_hw_shader_cache] (**enabled**|disabled) Awaiting description. - **Enable accurate geometry shaders (only for H/W shaders)** [citra_use_acc_geo_shaders] (**enabled**|disabled) Awaiting description. - **Enable accurate shaders multiplication (only for H/W shaders)** [citra_use_acc_mul] (**enabled**|disabled) Awaiting description. - **Texture filter type** [citra_texture_filter] (**none**|Anime4K Ultrafast|Bicubic|ScaleForce|xBRZ freescale) Awaiting description. - **Enable custom textures** [citra_custom_textures] (**disabled**|enabled) Awaiting description. - **Dump textures** [citra_dump_textures] (**disabled**|enabled) Awaiting description. - **Resolution scale factor** [citra_resolution_factor] (**1x (Native)**|2x|3x|4x|5x|6x|7x|8x|9x|10x) Self-explanatory. ??? note "Screen layout positioning - Default Top-Bottom Screen" ![](../image/core/citra/default.png) ??? note "Screen layout positioning - Single Screen Only" ![](../image/core/citra/single.png) ??? note "Screen layout positioning - Large Screen, Small Screen)" ![](../image/core/citra/large.png) - **Screen layout positioning** [citra_layout_option] (**Default Top-Bottom Screen**|Single Screen Only|Large Screen, Small Screen|Side by Side) Awaiting description. - **Prominent 3DS screen** [citra_swap_screen] (**Top**|Bottom) Awaiting description. - **Right analog function** [citra_analog_function] (**C-Stick and Touchscreen Pointer**|Touchscreen Pointer|C-Stick) Awaiting description. - **Emulated pointer deadzone (%)** [citra_deadzone] (**15**|20|25|30|35|0|5|10) Awaiting description. - **Simulate touchscreen interactions with mouse** [citra_mouse_touchscreen] (**enabled**|disabled) Awaiting description. - **Simulate touchscreen interactions with touchscreen** [citra_touch_touchscreen] (**disabled**|enabled) Awaiting description. - **Render simulated touchscreen interactions** [citra_render_touchscreen] (**disabled**|enabled) Awaiting description. - **Enable virtual SD card** [citra_use_virtual_sd] (**enabled**|disabled) Awaiting description. - **Savegame location** [citra_use_libretro_save_path] (**LibRetro Default**|Citra Default) Awaiting description. - **3DS system model** [citra_is_new_3ds] (**Old 3DS**|New 3DS) Awaiting description. - **3DS system region** [citra_region_value] (**Auto**|Japan|USA|Europe|Australia|China|Korea|Taiwan) Awaiting description. - **3DS system language** [citra_language] (**English**|Japanese|French|Spanish|German|Italian|Dutch|Portuguese|Russian|Korean|Traditional Chinese|Simplified Chinese) Awaiting description. - **"Enable GDB stub** [citra_use_gdbstub] (**disabled**|enabled) Awaiting description. ## Joypad | User 1 input descriptors | RetroPad Inputs | Citra inputs | |--------------------------|------------------------------------------------|--------------------| | B | ![](../image/retropad/retro_b.png) | B | | Y | ![](../image/retropad/retro_y.png) | Y | | Select | ![](../image/retropad/retro_select.png) | Select | | Start | ![](../image/retropad/retro_start.png) | Start | | Up | ![](../image/retropad/retro_dpad_up.png) | Up | | Down | ![](../image/retropad/retro_dpad_down.png) | Down | | Left | ![](../image/retropad/retro_dpad_left.png) | Left | | Right | ![](../image/retropad/retro_dpad_right.png) | Right | | A | ![](../image/retropad/retro_a.png) | A | | X | ![](../image/retropad/retro_x.png) | X | | L | ![](../image/retropad/retro_l1.png) | L | | R | ![](../image/retropad/retro_r1.png) | R | | ZL | ![](../image/retropad/retro_l2.png) | ZL | | ZR | ![](../image/retropad/retro_r2.png) | ZR | | Home | ![](../image/retropad/retro_l3.png) | Home | | Touch Screen Touch | ![](../image/retropad/retro_r3.png) | Touch Screen Touch | | | ![](../image/retropad/retro_left_stick.png) X | Circle Pad X | | | ![](../image/retropad/retro_left_stick.png) Y | Circle Pad Y | | | ![](../image/retropad/retro_right_stick.png) X | [Right analog function](#core-options) | | | ![](../image/retropad/retro_right_stick.png) Y | [Right analog function](#core-options) | ### Mouse | RetroMouse Inputs | Citra inputs | |-------------------------------------------------------|---------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Touchscreen Pointer | | ![](../image/retromouse/retro_left.png) Mouse 1 | Touch Screen Touch | ### Pointer | RetroPointer Inputs | Citra inputs | |--------------------------------------------------------------------------------------------------------------------------|---------------------| | ![](../image/retromouse/retro_mouse.png) or ![](../image/Button_Pack/Gestures/Gesture_Finger_Front.png) Pointer Position | Touchscreen Pointer | | ![](../image/retromouse/retro_left.png) or ![](../image/Button_Pack/Gestures/Gesture_Tap.png) Pointer Pressed | Touch Screen Touch | ## Compatibility - [Citra Game Compatibility List](https://citra-emu.org/game/) ## External Links - [Official Citra Website](https://citra-emu.org/) - [Official Citra Github Repository](https://github.com/citra-emu/citra) - [Libretro Citra Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/citra_libretro.info) - [Libretro Citra Github Repository](https://github.com/libretro/citra) - [Report Libretro Citra Core Issues Here](https://github.com/libretro/citra/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0IdQ7GmDs1jE7DbI18inc73c) ## Nintendo - Nintendo 3DS - [Nintendo - 3DS (Citra Canary/Experimental)](citra_canary.md) ================================================ FILE: docs/library/citra_canary.md ================================================ # Nintendo - 3DS (Citra Canary/Experimental) ## Background Citra is an experimental open-source Nintendo 3DS emulator/debugger written in C++. It is written with portability in mind. **Citra Canary is the new performance-optimized version of Citra.** The Citra Canary/Experimental core has been authored by - Citra Emulation Project The Citra Canary/Experimental core is licensed under - [GPLv2](https://github.com/citra-emu/citra/blob/master/license.txt) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ### Requirements OpenGL 3.3 or higher ![](../image/core/citra/gl.png) !!! warning There is currently no ‘working’ macOS version available. This is because this core requires OpenGL core 3.3 context, and RetroArch on macOS currently does not support this. We will have to add support for this to a future version of RetroArch on macOS before this core will start to work on it. ## Extensions Content that can be loaded by the Citra Canary/Experimental core have the following file extensions: - .3ds - .3dsx - .elf - .axf - .cci - .cxi - .app RetroArch database(s) that are associated with the Citra Canary/Experimental core: - [Nintendo - Nintendo 3DS](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%203DS.rdb) ## Features Frontend-level settings or features that the Citra Canary/Experimental core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Citra Canary/Experimental core's library name is 'Citra' The Citra Canary/Experimental core saves/loads to/from these directories. **Frontend's Save directory** - [Citra System and Save files](https://citra-emu.org/wiki/user-directory/) ### Geometry and timing - The Citra Canary/Experimental core's core provided FPS is 60.0 - The Citra Canary/Experimental core's core provided sample rate is 32728 Hz - The Citra Canary/Experimental core's base width is (Base width) - The Citra Canary/Experimental core's base height is (Base height) - The Citra Canary/Experimental core's max width is (Max width) - The Citra Canary/Experimental core's max height is (Max height) - The Citra Canary/Experimental core's core provided aspect ratio is (Ratio) ## Core options The Citra Canary/Experimental core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Enable CPU JIT** [citra_use_cpu_jit] (**enabled**|disabled) Enable Citra's 'dynarmic' dynamic recomplier. Can improve performance. Instructions that are not implemented by the recompiler fall back into the interpreter CPU core. If disabled, Citra will solely use the Interpreter CPU core. - **Select Renderer** [citra_renderer] (**enabled**|disabled) Awaiting description. - **Enable shader JIT** [citra_use_shader_jit] (**enabled**|disabled) Awaiting description. - **Resolution scale factor** [citra_resolution_factor] (**1x (Native)**|2x|3x|4x|5x|6x|7x|8x|9x|10x) Self-explanatory. ??? note "Screen layout positioning - Default Top-Bottom Screen" ![](../image/core/citra/default.png) ??? note "Screen layout positioning - Single Screen Only" ![](../image/core/citra/single.png) ??? note "Screen layout positioning - Large Screen, Small Screen)" ![](../image/core/citra/large.png) - **Screen layout positioning** [citra_layout_option] (**Default Top-Bottom Screen**|Single Screen Only|Large Screen, Small Screen|Side by Side) Awaiting description. - **Prominent 3DS screen** [citra_swap_screen] (**Top**|Bottom) Awaiting description. - **Right analog function** [citra_analog_function] (**C-Stick and Touchscreen Pointer**|Touchscreen Pointer|C-Stick) Awaiting description. - **Emulated pointer deadzone (%)** [citra_deadzone] (**15**|20|25|30|35|0|5|10) Awaiting description. - **What hardware shaders to enable** [citra_hw_shaders] (**None**|Partial|Full) Awaiting description. - **Enables accurate hardware shaders (infinity * 0 = 0), required for some games, though slow on some hardware** [citra_use_accurate_mul] (**enabled**|disabled) Awaiting description. - **Enable virtual SD card** [citra_use_virtual_sd] (**enabled**|disabled) Awaiting description. - **Savegame location** [citra_use_libretro_save_path] (**LibRetro Default**|Citra Default) Awaiting description. - **3DS system model** [citra_is_new_3ds] (**Old 3DS**|New 3DS) Awaiting description. - **3DS system region** [citra_region_value] (**Auto**|Japan|USA|Europe|Australia|China|Korea|Taiwan) Awaiting description. - **"Enable GDB stub** [citra_use_gdbstub] (**disabled**|enabled) Awaiting description. ## Joypad | User 1 input descriptors | RetroPad Inputs | Citra inputs | |--------------------------|------------------------------------------------|--------------------| | B | ![](../image/retropad/retro_b.png) | B | | Y | ![](../image/retropad/retro_y.png) | Y | | Select | ![](../image/retropad/retro_select.png) | Select | | Start | ![](../image/retropad/retro_start.png) | Start | | Up | ![](../image/retropad/retro_dpad_up.png) | Up | | Down | ![](../image/retropad/retro_dpad_down.png) | Down | | Left | ![](../image/retropad/retro_dpad_left.png) | Left | | Right | ![](../image/retropad/retro_dpad_right.png) | Right | | A | ![](../image/retropad/retro_a.png) | A | | X | ![](../image/retropad/retro_x.png) | X | | L | ![](../image/retropad/retro_l1.png) | L | | R | ![](../image/retropad/retro_r1.png) | R | | ZL | ![](../image/retropad/retro_l2.png) | ZL | | ZR | ![](../image/retropad/retro_r2.png) | ZR | | Home | ![](../image/retropad/retro_l3.png) | Home | | Touch Screen Touch | ![](../image/retropad/retro_r3.png) | Touch Screen Touch | | | ![](../image/retropad/retro_left_stick.png) X | Circle Pad X | | | ![](../image/retropad/retro_left_stick.png) Y | Circle Pad Y | | | ![](../image/retropad/retro_right_stick.png) X | [Right analog function](#core-options) | | | ![](../image/retropad/retro_right_stick.png) Y | [Right analog function](#core-options) | ### Mouse | RetroMouse Inputs | Citra inputs | |-------------------------------------------------------|---------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Touchscreen Pointer | | ![](../image/retromouse/retro_left.png) Mouse 1 | Touch Screen Touch | ### Pointer | RetroPointer Inputs | Citra inputs | |--------------------------------------------------------------------------------------------------------------------------|---------------------| | ![](../image/retromouse/retro_mouse.png) or ![](../image/Button_Pack/Gestures/Gesture_Finger_Front.png) Pointer Position | Touchscreen Pointer | | ![](../image/retromouse/retro_left.png) or ![](../image/Button_Pack/Gestures/Gesture_Tap.png) Pointer Pressed | Touch Screen Touch | ## Compatibility - [Citra Game Compatibility List](https://citra-emu.org/game/) ## External Links - [Official Citra Canary/Experimental Website](https://citra-emu.org/) - [Official Citra Canary/Experimental Github Repository](https://github.com/citra-emu/citra) - [Libretro Citra Canary/Experimental Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/citra_canary_libretro.info) - [Libretro Citra Canary/Experimental Github Repository](https://github.com/libretro/citra/tree/canary) - [Report Libretro Citra Canary/Experimental Core Issues Here](https://github.com/libretro/citra/issues) ## Nintendo - Nintendo 3DS - [Nintendo - 3DS (Citra)](citra.md) ================================================ FILE: docs/library/clownmdemu.md ================================================ # ClownMDEmu ## Background A highly-portable Sega Mega Drive emulator that aims to be as fast as possible without sacrificing accuracy. The ClownMDEmu core has been authored by: - Clownacy The ClownMDEmu core is licensed under: - [AGPLv3](https://github.com/Clownacy/clownmdemu-libretro/blob/master/LICENCE.txt) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the ClownMDEmu core have the following file extensions: - .bin - .md - .gen - .cue - .iso - .chd RetroArch database(s) that are associated with the ClownMDEmu core: - [Sega - Mega Drive - Genesis](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20Mega%20Drive%20-%20Genesis.rdb) - [Sega - Mega-CD - Sega CD](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20Mega-CD%20-%20Sega%20CD.rdb) ## Features Frontend-level settings or features that the ClownMDEmu core respects: | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✔ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✔ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Directories The ClownMDEmu core's library name is 'ClownMDEmu'. The ClownMDEmu core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:----------------------------:| | *.srm | Mega Drive/Genesis save data | | *.brm | Mega CD/Sega CD save data | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ## Geometry and timing - The ClownMDEmu core's core-provided FPS is 59.94 for NTSC games and 50 for PAL games - The ClownMDEmu core's core-provided sample rate is 223721.5625 Hz - The ClownMDEmu core's base width is 320 (though this varies depending on the loaded content) - The ClownMDEmu core's base height is 224 (though this varies depending on the loaded content) - The ClownMDEmu core's max width is 512 - The ClownMDEmu core's max height is 480 - The ClownMDEmu core's core-provided aspect ratio is typically 10:7 (though this varies depending on the loaded content) ## Core options The ClownMDEmu core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. - **Debug > Disable Sprite Plane** [clownmdemu_disable_sprite_plane] (**disabled**|enabled) Disable the VDP's Sprite Plane. - **Debug > Disable Window Plane** [clownmdemu_disable_window_plane] (**disabled**|enabled) Disable the VDP's Window Plane. - **Debug > Disable Plane A** [clownmdemu_disable_plane_a] (**disabled**|enabled) Disable the VDP's Plane A. - **Debug > Disable Plane B** [clownmdemu_disable_plane_b] (**disabled**|enabled) Disable the VDP's Plane B. - **Debug > Disable FM1** [clownmdemu_disable_fm1] (**disabled**|enabled) Disable the YM2612's FM1 channel. - **Debug > Disable FM2** [clownmdemu_disable_fm2] (**disabled**|enabled) Disable the YM2612's FM2 channel. - **Debug > Disable FM3** [clownmdemu_disable_fm3] (**disabled**|enabled) Disable the YM2612's FM3 channel. - **Debug > Disable FM4** [clownmdemu_disable_fm4] (**disabled**|enabled) Disable the YM2612's FM4 channel. - **Debug > Disable FM5** [clownmdemu_disable_fm5] (**disabled**|enabled) Disable the YM2612's FM5 channel. - **Debug > Disable FM6** [clownmdemu_disable_fm6] (**disabled**|enabled) Disable the YM2612's FM6 channel. - **Debug > Disable DAC** [clownmdemu_disable_dac] (**disabled**|enabled) Disable the YM2612's DAC channel. - **Debug > Disable PSG1** [clownmdemu_disable_psg1] (**disabled**|enabled) Disable the SN76496's PSG1 channel. - **Debug > Disable PSG2** [clownmdemu_disable_psg2] (**disabled**|enabled) Disable the SN76496's PSG2 channel. - **Debug > Disable PSG3** [clownmdemu_disable_psg3] (**disabled**|enabled) Disable the SN76496's PSG3 channel. - **Debug > Disable PSG Noise** [clownmdemu_disable_psg_noise] (**disabled**|enabled) Disable the SN76496's PSG Noise channel. - **Debug > Disable PCM1** [clownmdemu_disable_pcm1] (**disabled**|enabled) Disable the RF5C164's PCM1 channel. - **Debug > Disable PCM2** [clownmdemu_disable_pcm2] (**disabled**|enabled) Disable the RF5C164's PCM2 channel. - **Debug > Disable PCM3** [clownmdemu_disable_pcm3] (**disabled**|enabled) Disable the RF5C164's PCM3 channel. - **Debug > Disable PCM4** [clownmdemu_disable_pcm4] (**disabled**|enabled) Disable the RF5C164's PCM4 channel. - **Debug > Disable PCM5** [clownmdemu_disable_pcm5] (**disabled**|enabled) Disable the RF5C164's PCM5 channel. - **Debug > Disable PCM6** [clownmdemu_disable_pcm6] (**disabled**|enabled) Disable the RF5C164's PCM6 channel. - **Debug > Disable PCM7** [clownmdemu_disable_pcm7] (**disabled**|enabled) Disable the RF5C164's PCM7 channel. - **Debug > Disable PCM8** [clownmdemu_disable_pcm8] (**disabled**|enabled) Disable the RF5C164's PCM8 channel. - **Debug > Disable CDDA** [clownmdemu_disable_cdda] (**disabled**|enabled) Disable the CDDA channel. - **Console > TV Standard** [clownmdemu_tv_standard] (**ntsc**|pal) Which television standard to output in. - **Console > Region** [clownmdemu_overseas_region] (**elsewhere**|japan) Which region the console is. - **Console > CD Add-on** [clownmdemu_cd_addon] (**disabled**|enabled) Allow cartridge-only software to utilise features of the emulated Mega CD add-on, such as CD music. This may break some software. - **Video > Tall Interlace Mode 2** [clownmdemu_tall_interlace_mode_2] (**disabled**|enabled) Makes games that use Interlace Mode 2 for split-screen not appear squashed. - **Video > Widescreen Hack** [clownmdemu_widescreen_tiles] (**0**|1|2|3|4|5|6|7|8|9|10|11|12) Widens the display. Works well with some games, badly with others. - **Audio > Low-Pass Filter** [clownmdemu_lowpass_filter] (**enabled**|disabled) Lowers the volume of high frequencies to make the audio 'softer', like a real Mega Drive does. Without this, treble will become louder due to differences in volume balancing. - **Audio > Low-Volume Distortion** [clownmdemu_ladder_effect] (**enabled**|disabled) Enables the so-called 'ladder effect' that is present in early Mega Drives. Without this, some quiet sounds will become inaudible. ## Joypad ![](../image/controller/md6.png) | RetroPad Inputs | User 1 - 2 input descriptors | |------------------------------------------------|------------------------------| | ![](../image/retropad/retro_b.png) | B | | ![](../image/retropad/retro_y.png) | A | | ![](../image/retropad/retro_select.png) | Mode | | ![](../image/retropad/retro_start.png) | Start | | ![](../image/retropad/retro_dpad_up.png) | Up | | ![](../image/retropad/retro_dpad_down.png) | Down | | ![](../image/retropad/retro_dpad_left.png) | Left | | ![](../image/retropad/retro_dpad_right.png) | Right | | ![](../image/retropad/retro_a.png) | C | | ![](../image/retropad/retro_x.png) | Y | | ![](../image/retropad/retro_l1.png) | X | | ![](../image/retropad/retro_r1.png) | Z | ## External links - [Official ClownMDEmu Website](https://clownmdemu.clownacy.com) - [Official ClownMDEmu GitHub Repository](https://github.com/Clownacy/clownmdemu-libretro) - [Libretro ClownMDEmu Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/clownmdemu_libretro.info) - [Report Libretro ClownMDEmu Core Issues Here](https://github.com/Clownacy/clownmdemu-libretro/issues) ## Sega Mega Drive/Genesis cores - [Sega - Mega Drive - Genesis (BlastEm)](blastem.md) - [Sega - MS/GG/MD/CD (Genesis Plus GX)](genesis_plus_gx.md) - [Sega - MS/MD/CD/32X (PicoDrive)](picodrive.md) ================================================ FILE: docs/library/compatibility/32x.md ================================================ # Sega 32X Core Compatibility ## PicoDrive | Game | Issue | |----------------------------------------------|---------------------------------------------------------------| | Brutal Unleashed – Above the Claw | Softlocks after the first fight. | | FIFA Soccer ’96 | Glitched main menu text. | | Knuckles’ Chaotix | Glitched graphics on the Player Select screen. | | NBA Jam Tournament Edition | Framerate issues. | | NFL Quarterback Club | Some menu graphics are missing. | | Virtua Racing Deluxe | Blinking line during the SEGA logo screen. | | World Series Baseball Starring Deion Sanders | Crashes when starting a match. | | WWF Raw | Various graphics are missing. | ================================================ FILE: docs/library/compatibility/3do.md ================================================ # 3DO Core Compatibility ## Opera [Opera Core Compatibility List](http://wiki.fourdo.com/Compatibility_List) ================================================ FILE: docs/library/compatibility/dc.md ================================================ # Sega Dreamcast Core Compatibility ## FlyCast General FlyCast Issues - The date and time do not seem to get properly saved, as the system will ask you to set the clock every time you start. - Once you save to a VMU slot with any game, that VMU becomes inaccessible the next time you load the emulator. - Polygon/Alpha sorting issues can make objects appear distorted in regular Flycast core. Use Per-Pixel Alpha sorting if you want complete/accurate emulation instead. - When using an Xbox 360 Controller, analog triggers don't work properly. Use the bumpers instead. - Changing games without closing and reloading RetroArch often leads to RetroArch crashing. | Game | Issue | |---------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Sonic Adventure (PAL) | Must be set to use "VGA" output in core options, as "TV" mode will cause all subsequent FMV to make RetroArch become unresponsive. | | The Typing of the Dead (NTSC-J) | Must have real BIOS for kanji, hiragana, and katakana to show up since HLE BIOS only has US/ASCII characters. | ================================================ FILE: docs/library/compatibility/ds.md ================================================ # Nintendo DS Core Compatibility ## DeSmuME | Game | Issue | |------------------------------------------|-----------------------------------------------------------------------------------------------| | Alice in Wonderland | Needs JIT Block Size 8 or smaller to get past title screen. | | Golden Sun: Dark Dawn (Europe) | Runs very slowly. Buggy sound. | | Hotel Dusk: Room 215 | Graphics glitches. Unintended "scanlines" appear on some screens. | | Pokémon HeartGold (Europe) (Rev 10) | Graphics glitches . Black pixels pop-ups in the top screen. Top screen goes black. | | Pokémon SoulSilver (Europe) (Rev 10) | Graphics glitches. Black pixels pop-ups in the top screen. Top screen goes black. | | Puppy Palace (U) / My Puppy Shop (E) | Crashes in menus. | | Rune Factory (U) | Random crashes. | | Rune Factory 2 (U) | Random crashes. | | Ultimate Mortal Kombat 3 | Runs very slowly. | | | Yoshi Touch & Go | Runs very slowly. | | Yu-Gi-Oh! 5D's WORLD CHAMPIONSHIP 2010 (J) | Random crashes. | ================================================ FILE: docs/library/compatibility/gba.md ================================================ # Nintendo Game Boy Advance Core Compatibility Please notice that when using these cores on RetroArch, [only certain cores support libretro save interface](https://github.com/libretro/RetroArch/issues/16323#issuecomment-1977792161), meaning even if you set option "SaveRAM Autosave Interval" on settings, some cores will only write down internal save game data when you gracefully close emulation. That might lead to loss of data if you exit RetroArch from your OS app switcher, if it freezes or if shuts down unexpectedly without battery for instance. ## Beetle GBA [Does not support SaveRAM Autosave Interval.](https://github.com/libretro/RetroArch/issues/16323#issuecomment-1980460281) ## gpSP [Does not support SaveRAM Autosave Interval.](https://github.com/libretro/RetroArch/issues/16323#issuecomment-1980460281) | Game | Issue | |---------------------------------------|--------------------------------| | ~~Activision Anthology~~ |~~Freezes when entering a game.~~ | | ~~Banjo-Kazooie - Grunty's Revenge~~ |~~Black screen during developer logo. Resets when Banjo leaves his house.~~| | Boktai Trilogy |The solar sensor is not emulated. | | ~~DemiKids - Light/Dark Version~~ |~~Crashes when entering a battle.~~ | | ~~Digimon Racing (Europe)~~ |~~Freezes during the intro.~~ | | ~~Dragon Ball Z - The Legacy of Goku~~ |~~Graphics glitches.~~ | | Final Fantasy VI |Background/tiling order issues. | | Golden Sun 1 and 2 |Background/tiling order issues (GS1 Carpet on Ship / GS2 Ice shards in cave). | | ~~Game Boy Advance Video - Dragon Ball GT - Volume 1~~ |~~White screen.~~ | | ~~Grand Theft Auto Advance~~ |~~Crashes after first dialog. Works on some platforms.~~ | | ~~Harry Potter - Quidditch World Cup~~ |~~Crashes when going ingame.~~ | | Koro Koro Puzzle Happy Panechu! |The tilt sensor is not emulated. | | ~~Mario & Luigi - Superstar Saga~~ |~~Sometimes crashes when entering a battle.~~ | | Phantasy Star Collection |Phantasy Star 1 flickers - turn on Interframe Blending in core options to fix.| | ~~R-Type III - The Third Lightning~~ |~~Softlocks at Irem startup screen.~~| | ~~Rock 'n Roll Racing~~ |~~Corrupted graphics, not playable.~~| | ~~Rockman & Forte~~ |~~Doesn't continue after GBA BIOS screen.~~| | Sims 2, The - Pets |Graphics glitches. Heavy flickering, black objects. | | Street Racing Syndicate |Crashes at startup screen, after pressing Start (Works in Interpreter Mode in lr-gpsp v1.0.0).| | ~~Super Monkey Ball Jr.~~ |~~Softlocks at startup screen.~~| | ~~Super Street Fighter II Turbo/X Revival~~ |~~Small graphics glitch. Selecting speed 'Turbo 1' and beyond on the character select screen makes the game speed window not fully visible.~~ | | ~~Tales of Phantasia (USA version)~~ |~~Softlocks during the introduction sequence (just before the small guy hits the tall guy in the right).~~| | WarioWare: Twisted! |The tilt sensor is not emulated.| | ~~Wolfenstein 3D~~ |~~Softlocks at id Software startup screen.~~| | Yoshi’s Universal Gravitation |The tilt sensor is not emulated.| ## mGBA [Supports SaveRAM Autosave Interval.](https://github.com/libretro/RetroArch/issues/16323#issuecomment-1980460281) ## VBA-M [Supports SaveRAM Autosave Interval.](https://github.com/libretro/RetroArch/issues/16323#issuecomment-1980460281) | Game | Issue | |---------------------------------------|--------------------------------| | ~~Boktai Trilogy~~ | ~~The solar sensor is not emulated~~| | ~~Digimon Racing (Europe)~~ |~~Freezes during the intro. This can be avoided by enabling linking in the standalone VBA-M release~~ | | ~~Koro Koro Puzzle Happy Panechu!~~ | ~~The tilt sensor is not emulated~~| | ~~Phantasy Star Collection~~ | ~~Digital Eclipse logo sound effect is missing. Phantasy Star 1 flickers~~ | | ~~WarioWare: Twisted!~~ | ~~The tilt sensor is not emulated~~ | | ~~Yoshi’s Universal Gravitation~~ | ~~The tilt sensor is not emulated~~ | ## VBA Next [Supports SaveRAM Autosave Interval.](https://github.com/libretro/RetroArch/issues/16323#issuecomment-1980460281) | Game | Issue | |---------------------------------------------------|----------------------------------------------------------------------------------------------------| | Boktai Trilogy | The solar sensor is not emulated. | | Croket! 2 – Yami no Bank to Banqueen | Heavy slowdown when approaching the snowman in the beginning. | | Digimon Racing (Europe) | Freezes during the intro. This can be avoided by enabling linking in the standalone VBA-M release. | | Drome Racers | Only shows a black screen after the THQ logo. | | Hamtaro: Ham-Ham Games | Locks up if the opening cinematics aren’t skipped. | | Hot Wheels - Stunt Track Challenge | Resets itself when trying to go in-game. | | Jurassic Park III: Park Builder | Unreadable glitched text. | | Koro Koro Puzzle Happy Panechu! | The tilt sensor is not emulated. | | Moto GP | Black screen, loud screeching noise. | | Sanrio Puroland: All Characters | Loads Indefinitely. Very slow. | | Phantasy Star Collection | Digital Eclipse logo sound effect is missing. Phantasy Star 1 flickers. | | SSX 3 | Graphics glitches. Seems pitch-related. | | Super Mario Advance 2: Super Mario World (Europe) | The program crashes during the final fight, when Bowser approaches (zoom mode 7) | | WarioWare: Twisted! | The tilt sensor is not emulated. | | Yoshi’s Universal Gravitation | The tilt sensor is not emulated. | ================================================ FILE: docs/library/compatibility/gbc.md ================================================ # Nintendo Game Boy Color Core Compatibility ## Gambatte | Game | Issue | |---------------------------------------------------|----------------------------------------------------| | Command Master | Crashes on start. Unemulated MBC7 mapper. | | Game Boy Camera | Crashes on start. Unemulated Pocket Camera mapper. | | Game de Hakken!! Tamagotchi - Osutchi to Mesutchi | Crashes on start. Unemulated TAMA5 mapper. | | Kirby Tilt 'n' Tumble | Crashes on start. Unemulated MBC7 mapper. | | Net de Get: Mini-Game @ 100 | Crashes on start. Unemulated MBC6 mapper. | ================================================ FILE: docs/library/compatibility/jaguar.md ================================================ # Atari Jaguar Core Compatibility ## Virtual Jaguar A reference compatibility table can be found here [https://icculus.org/virtualjaguar/](https://icculus.org/virtualjaguar/) | Game | Issue | |--------------------|-------------------------------------------------------- | | Cybermorph | Graphics glitches. | | Doom | Enable Doom core option hack for proper graphics pitch. | | Iron Soldier | Hangs after selecting a stage. | | Iron Soldier 2 | Hangs after selecting a stage. Audio glitches. | | Kasumi Ninja | Graphics glitches. Missing background layers | | Ruiner Pinball | Doesn't boot. | | Super Burnout | Hangs after selecting a track. | | Towers II | Heavy flickering. | | Wolfenstein 3D | Doesn't boot. | ================================================ FILE: docs/library/compatibility/lynx.md ================================================ # Atari Lynx Core Compatibility ## Handy | Game | Issue | |------------------|-------------------------------------------------------------------------| | RoadBlasters | Graphics glitches. Minor flickering and glitches after starting a race. | ## Beetle Lynx | Game | Issue | |------------------|-------------------------------------------------------------------------| | RoadBlasters | Graphics glitches. Minor flickering and glitches after starting a race. | ================================================ FILE: docs/library/compatibility/nes.md ================================================ # Nintendo NES Core Compatibility ## Nestopia | Game | Issue | |------------------------|----------------------------------------------------------------- | | ~~Skull & Crossbones~~ | ~~Graphical glitches and screen shaking when in 2-player mode.~~ Fixed! | ## FCEUmm | Game | Issue | |------------------------------|--------------------------------------------------------------| | Skull & Crossbones | Graphical glitches and screen shaking when in 2-player mode. | ## bnes | Game | Issue | |------------------------------|------------------------------------------------| | Crisis Force | Graphical glitches. | | Huge Insect | No enemies spawn. | | Lagrange Point | No music. | | Ms. Pac-Man (Tengen version) | Graphical glitches on the sides of the screen. | | Skull & Crossbones | Crashes on start. | ## QuickNES | Game | Issue | |--------------------|-------------------------------------------------------------------------------| | Burai Fighter | Softlocks when entering a level. Confirmed issue. MMC3 incompatible. | | Family Circuit '91 | Crashes on start. Unsupported Mapper 210. | | Huge Insect | No enemies spawn. Mapper 3 confirmed issue. Unemulated bus conflict handling. | | Skull & Crossbones | Crashes on start. Unsupported Mapper. | ================================================ FILE: docs/library/compatibility/pcfx.md ================================================ # NEC PC-FX Core Compatibility ## Beetle PC-FX | Game | Issue | |---------------------------------------------------------------------|---------------------------------------------------| | Pia Carrot e Youkoso!! (Japan) [T-En by David Michel + filler v1.0] | Doesn't boot. Confirmed to work on real hardware. | ================================================ FILE: docs/library/compatibility/psx.md ================================================ # PlayStation Core Compatibility ## Beetle PSX A list of known emulation bugs can be found here [https://forum.fobby.net/index.php?t=msg&th=1114&start=0&](https://forum.fobby.net/index.php?t=msg&th=1114&start=0&) ## PCSX ReARMed | Game | Issue | |--------------------------|--------------------------------------------------------| | Jumping Flash 2 | Graphics glitches. Geometry issues. | | Tobal 2 | Graphics glitch. Garbled Dream Factory intro sequence. | | Hot Wheels: Turbo Racing | Black screen after intro video | ================================================ FILE: docs/library/compatibility/saturn.md ================================================ # Sega Saturn Core Compatibility ## Yabause [Official Yabause Compatibility List](https://wiki.yabause.org/index.php5?title=Compatibility_list) ## Kronos [Official Kronos Compatibility List](http://tradu-france.com/tfwiki-1.28.2/index.php?title=Compatibility_list_of_Kronos) ================================================ FILE: docs/library/compatibility/snes.md ================================================ # Nintendo SNES Core Compatibility ## bsnes Accuracy The bsnes Accuracy core fully emulates all SNES games that have ever been officially released. Same with bsnes-mercury Accuracy ## bsnes Balanced | Game | Issue | |--------------------------|--------------------------------------------------------------------------------| | A.S.P. Air Strike Patrol | Black lines show up during gameplay. The shadow below the aircraft is missing. | Same with bsnes-mercury Balanced ## bsnes Performance | Game | Issue | |--------------------------------------------------|--------------------------------------------------------------------------------| | A.S.P. Air Strike Patrol | Black lines show up during gameplay. The shadow below the aircraft is missing. | | Funaki Masakatsu Hybrid Wrestler – Tougi Denshou | Corrupted graphics on the Pancrase logo screen. | | Mecarobot Golf | The ground "wobbles" during gameplay. | | Mega Man X2 | Only displays a black screen. | | Mega Man X3 | Only displays a black screen. | | Mortal Kombat II | Various glitched graphics. | | NHL ’94 | Corrupted line on the NHL logo screen. | | Tetris Attack | Lots of flickering on the VS. CPU mode map screen. | Same with bsnes-mercury Performance ## Snes9x 2005 | Game | Issue | |--------------------------------------------------|--------------------------------------------------------------------------------------| | A.S.P. Air Strike Patrol | The shadow below the aircraft is missing. Glitched graphics on the briefing screens. | | Bass Masters Classic - Pro Edition | Only shows a black screen. | | Funaki Masakatsu Hybrid Wrestler – Tougi Denshou | Corrupted graphics on the Pancrase logo screen. | | Hayazashi Nidan Morita Shougi 2 | Matches won’t start. | | Madden NFL 96 | Only shows a black screen. | | Masters New – Harukanaru Augusta 3 | Black screen after selecting game. | | Mecarobot Golf | The ground "wobbles" during gameplay. | | Mechwarrior 3050 | Black screen after the Activision logo. | Same with Snes9x 2005 Plus ## Snes9x 2010 | Game | Issue | |--------------------------------------------------|---------------------------------------------------------------------------------------| | A.S.P. Air Strike Patrol | The shadow below the aircraft is missing. Glitched graphics on the briefing screens. | | Bass Masters Classic - Pro Edition | Only shows a black screen. | | Doom | Colored dots appear during gameplay. | | F-1 Grand Prix | Glitched HUD display. | | F1 ROC II – Race of Champions | Crashes when starting a race. | | Funaki Masakatsu Hybrid Wrestler – Tougi Denshou | Corrupted graphics on the Pancrase logo screen. | | Hayazashi Nidan Morita Shougi 2 | Matches won’t start. | | Madden NFL 96 | Only shows a black screen. | | Masters New – Harukanaru Augusta 3 | Graphical corruption during gameplay. | | Mecarobot Golf | The ground "wobbles" during gameplay. | | Mechwarrior 3050 | Black screen after the Activision logo. | | Secret of Evermore (PAL) | Randomly freezes when the background music changes. | | Sink or Swim | Sometimes the levels are filled with water instantly. | | Speedy Gonzales: Los Gatos Bandidos | Freezes when pressing a switch in the last level. | | Super Bomberman 3 | Freezes after about 20 seconds in the Battle mode menu. | | Super Bomberman 5 | Title screen flickers if the opening cinematic isn’t skipped. | ## Snes9x | Game | Issue | |--------------------------------------------------|--------------------------------------------------------------------------------------| | A.S.P. Air Strike Patrol | The shadow below the aircraft is missing. Glitched graphics on the briefing screens. | | BS-Zelda MottZilla Patch | Only shows a black screen. | | Doom | Colored dots appear during gameplay. | | Funaki Masakatsu Hybrid Wrestler – Tougi Denshou | Corrupted graphics on the Pancrase logo screen. | | Hayazashi Nidan Morita Shougi 2 | Matches won’t start. | | Mecarobot Golf | The ground "wobbles" during gameplay. | | Secret of Evermore (PAL versions) | Randomly freezes when the background music changes. | ## higan Accuracy The higan Accuracy core fully emulates all SNES games that have ever been officially released. ## nSide Balanced | Game | Issue | |--------------------------|--------------------------------------------------------------------------------| | A.S.P. Air Strike Patrol | Black lines show up during gameplay. The shadow below the aircraft is missing. | ================================================ FILE: docs/library/compatibility/wswan.md ================================================ # Bandai Wonderswan Core Compatibility ## Beetle Cygne | Game | Issue | |-----------|------------------------------------------------------------------------------| | Tonpuusou | Title screen announcer voice missing. Softlocks after picking a menu option. | ================================================ FILE: docs/library/craft.md ================================================ # Minecraft (Craft) ## Background A simple Minecraft clone written in C using modern OpenGL (shaders). ## Features - Simple but nice looking terrain generation using simplex noise. - Biomes - Water - More than 20 types of blocks and more can be added easily. - Supports plants (grass, flowers, trees, etc.) and transparency (glass). - Simple clouds in the sky (they don't move). - Day / night cycles and a textured sky dome. - More sophisticated sunrise/sunset color blending - Ambient occlusion for basic shading of blocks. - World changes persisted in a sqlite3 database. - Configurable draw distance. The draw distance has a big effect on the framerate, a draw distance of 1 or 2 can make this core playable even on very lightweight computers. - Configurable field of view. - Gamepad support (including analog stick support) configurable analog sensitivity and deadzones, preliminary mouse and keyboard support. - Configurable resolutions, up to 4K. - A ‘Jumping Flash’ mode that allows you to jump infinitely into the air all while the camera faces downwards. The Craft core has been authored by - Michael Fogleman The Craft core is licensed under - [MIT](https://github.com/libretro/Craft/blob/master/LICENSE.md) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Requirements - OpenGL or OpenGL ES ## How to start the Craft core: - To start the Craft core, go to RetroArch's main menu screen. Select 'Load Core', then 'Craft'. - Now, select 'Start Core'. The content should now start running! ## Features Frontend-level settings or features that the Craft core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✕ | | Saves | ✔ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✕ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Directories The Craft core's library name is 'Craft' The Craft core saves/loads to/from these directories. **Frontend's System directory** | File | Description | |:--------:|:-----------:| | craft.db | World data | ## Geometry and timing - The Craft core's core provided FPS is 60.0 - The Craft core's core provided sample rate is 48000 Hz - The Craft core's base width is 640 - The Craft core's base height is 480 - The Craft core's max width is 640 - The Craft core's max height is 480 - The Craft core's core provided aspect ratio is 16/9 ## Core options The Craft core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Resolution (restart)** [craft_resolution] (**640x480**|320x200|640x400|960x600|1280x800|1600x1000|1920x1200|2240x1400|2560x1600|2880x1800|3200x2000|3520x2200|3840x2400|7680x4320|15360x8640|16000x9000|320x240|320x480|360x200|360x240|360x400|360x480|400x224|480x272|512x224|512x240|512x384|512x512|640x224|640x240|640x448|720x576|800x480|800x600|960x720|1024x768|1280x720|1366x768|1600x900|1920x1080|2048x2048|4096x4096) Configure the resolution. ??? note "Resolution - 320x240" ![](../image/core/craft/320.png) ??? note "Resolution - 1920x1080" ![](../image/core/craft/1920.png) - **Show info text** [craft_show_info_text] (**disabled**|enabled) Show game information in the upper left corner of Craft. ??? note "Show info text - Off" ![](../image/core/craft/off.png) ??? note "Show info text - On" ![](../image/core/craft/on.png) - **Jumping Flash mode** (**Off**/On): Enabling this allows you to jump infinitely into the air all while the camera faces downwards. - **Field of view** [craft_field_of_view] (**65** to 150 in increments of 5) Configure the field of view. ??? note "Field of view - 65" ![](../image/core/craft/65.png) ??? note "Field of view - 125" ![](../image/core/craft/125.png) - **Draw distance** [craft_draw_distance] (1 to 32 in increments of 1. **10 is default**) Configure the draw distance. ??? note "Draw distance - 10" ![](../image/core/craft/10.png) ??? note "Draw distance - 32" ![](../image/core/craft/32.png) - **Inverted aim** [craft_inverted_aim] (**disabled**|enabled) Invert up and down crosshair aiming controls for the RetroPad and the RetroMouse. - **Right analog sensitivity** [craft_analog_sensitivity] (**0.0150** to 0.0500 in increments of 0.0025) Modify the RetroPad right analog stick's sensitivity. - **Analog deadzone size** [craft_deadzone_radius] (**0.010** to 0.200 in increments of 0.005) Modify RetroPad analog sticks' deadzone. ## Joypad | RetroPad Inputs | Craft Inputs | |------------------------------------------------|---------------------------| | ![](../image/retropad/retro_b.png) | Jump | | ![](../image/retropad/retro_y.png) | Destroy block | | ![](../image/retropad/retro_select.png) | Zoom out | | ![](../image/retropad/retro_dpad_up.png) | Move forwards | | ![](../image/retropad/retro_dpad_down.png) | Move backwards | | ![](../image/retropad/retro_dpad_left.png) | Move crosshair left | | ![](../image/retropad/retro_dpad_right.png) | Move crosshair right | | ![](../image/retropad/retro_a.png) | Next block | | ![](../image/retropad/retro_x.png) | Place block | | ![](../image/retropad/retro_l1.png) | Move left | | ![](../image/retropad/retro_r1.png) | Move right | | ![](../image/retropad/retro_l2.png) | Move crosshair up | | ![](../image/retropad/retro_r2.png) | Move crosshair down | | ![](../image/retropad/retro_left_stick.png) X | Move left/right | | ![](../image/retropad/retro_left_stick.png) Y | Move up/down | | ![](../image/retropad/retro_right_stick.png) X | Move crosshair left/right | | ![](../image/retropad/retro_right_stick.png) Y | Move crosshair up.down | ## Keyboard | RetroKeyboard Inputs | Craft Inputs | |----------------------|----------------------| | Keyboard Up | Move forwards | | Keyboard Down | Move backwards | | Keyboard Right | Move crosshair left | | Keyboard Left | Move crosshair right | | Keyboard Right Shift | Zoom out | ## Mouse | RetroMouse Inputs | Craft Inputs | |-------------------------------------------------------|----------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Move crosshair | | ![](../image/retromouse/retro_left.png) Mouse 1 | Destroy block | | ![](../image/retromouse/retro_right.png) Mouse 2 | Place block | | ![](../image/retromouse/retro_middle.png) Mouse 3 | Copy block | | Wheel Up | Previous block | | Wheel Down | Next block | ## External Links - [Official Craft Website](https://www.michaelfogleman.com/projects/craft/) - [Official Craft Github Repository](https://github.com/fogleman/Craft) - [Libretro Craft Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/craft_libretro.info) - [Libretro Craft Github Repository](https://github.com/libretro/craft) - [Report Libretro Craft Core Issues Here](https://github.com/libretro/Craft/issues) ================================================ FILE: docs/library/crocods.md ================================================ # Amstrad - CPC (CrocoDS) ## Background Based on Win-CPC. CrocoDS was originally an Amstrad CPC emulator created for the Nintendo DS and was ported to libretro some time after. ### Author/License The CrocoDS core has been authored by - RedBug The CrocoDS core is licensed under - [MIT](https://github.com/libretro/libretro-crocods/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the CrocoDS core have the following file extensions: - .dsk - .sna - .[kcr](https://github.com/redbug26/crocods-core/wiki/kcr) ## Databases RetroArch database(s) that are associated with the CrocoDS core: - [Amstrad - CPC](https://github.com/libretro/libretro-database/blob/master/rdb/Amstrad%20-%20CPC.rdb) ## Features Frontend-level settings or features that the CrocoDS core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✕ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The CrocoDS core's internal core name is 'crocods' The CrocoDS core saves/loads to/from these directories. **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The CrocoDS core's core provided FPS is 50 - The CrocoDS core's core provided sample rate is 44100 Hz - The CrocoDS core's core provided aspect ratio is 1 ## Core options The CrocoDS core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Color Monitor** [crocods_greenmonitor] (**color**|green) Self-explanatory. ??? note "Color Monitor - color" ![](../image/core/crocods/color.png) ??? note "Color Monitor - green" ![](../image/core/crocods/green.png) - **Resize** [crocods_resize] (**Auto**|320x200|Overscan) Self-explanatory. ??? note "Resize - 320x200" ![](../image/core/crocods/320x200.png) ??? note "Resize - Overscan" ![](../image/core/crocods/overscan.png) - **Speed hack** [crocods_hack] (**no**|yes) Awaiting description. ## Controllers The CrocoDS core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 - 2 device types - None - Doesn't disable input. There's no reason to switch to this. - **RetroPad** - Joypad - RetroKeyboard - Joypad - Keyboard inputs are always active. Has keymapper support. ### Controller tables #### Joypad | User 1 Remap descriptors | RetroPad Inputs | CrocoDS core inputs | |--------------------------|------------------------------------------------|---------------------| | | ![](../image/retropad/retro_b.png) | JOY_FIRE2 | | | ![](../image/retropad/retro_y.png) | NIL | | Pause | ![](../image/retropad/retro_select.png) | SPARE | | Start | ![](../image/retropad/retro_start.png) | RETURN | | Up | ![](../image/retropad/retro_dpad_up.png) | JOY_UP | | Down | ![](../image/retropad/retro_dpad_down.png) | JOY_DOWN | | Left | ![](../image/retropad/retro_dpad_left.png) | JOY_LEFT | | Right | ![](../image/retropad/retro_dpad_right.png) | JOY_RIGHT | | | ![](../image/retropad/retro_a.png) | JOY_FIRE1 | | | ![](../image/retropad/retro_x.png) | NIL | | | ![](../image/retropad/retro_l1.png) | NIL | | | ![](../image/retropad/retro_r1.png) | NIL | | User 2 Remap descriptors | RetroPad Inputs | CrocoDS core inputs | |--------------------------|------------------------------------------------|---------------------| | | ![](../image/retropad/retro_b.png) | SPARE | | | ![](../image/retropad/retro_y.png) | NIL | | | ![](../image/retropad/retro_select.png) | SPARE | | | ![](../image/retropad/retro_start.png) | RETURN | | | ![](../image/retropad/retro_dpad_up.png) | CURSOR_UP | | | ![](../image/retropad/retro_dpad_down.png) | CURSOR_DOWN | | | ![](../image/retropad/retro_dpad_left.png) | CURSOR_LEFT | | | ![](../image/retropad/retro_dpad_right.png) | CURSOR_RIGHT | | | ![](../image/retropad/retro_a.png) | SPARE | | | ![](../image/retropad/retro_x.png) | NIL | | | ![](../image/retropad/retro_l1.png) | NIL | | | ![](../image/retropad/retro_r1.png) | NIL | #### Keyboard | RetroKeyboard Inputs | CrocoDS core Inputs | |------------------------------|---------------------| | Keyboard Backspace | DEL | | Keyboard Tab | TAB | | Keyboard Return | RETURN | | Keyboard Escape | ESC | | Keyboard Space | SPARE | | Keyboard Comma , | COMMA | | Keyboard Minus - | MINUS | | Keyboard Period . | DOT | | Keyboard 0 | 0 | | Keyboard 1 | 1 | | Keyboard 2 | 2 | | Keyboard 3 | 3 | | Keyboard 4 | 4 | | Keyboard 5 | 5 | | Keyboard 6 | 6 | | Keyboard 7 | 7 | | Keyboard 8 | 8 | | Keyboard 9 | 9 | | Keyboard Semicolon ; | COLON | | Keyboard Equals = | HAT | | Keyboard Left Bracket [ | AT | | Keyboard Right Bracket ] | OPEN_SQUARE_BRACKET | | Keyboard a | A | | Keyboard b | B | | Keyboard c | C | | Keyboard d | D | | Keyboard e | E | | Keyboard f | F | | Keyboard g | G | | Keyboard h | H | | Keyboard i | I | | Keyboard j | J | | Keyboard k | K | | Keyboard l | L | | Keyboard m | M | | Keyboard n | N | | Keyboard o | O | | Keyboard p | P | | Keyboard q | Q | | Keyboard r | R | | Keyboard s | S | | Keyboard t | T | | Keyboard u | U | | Keyboard v | V | | Keyboard w | W | | Keyboard x | X | | Keyboard y | Y | | Keyboard z | Z | | Keyboard Delete | JOY_LEFT | | Keyboard Keypad 0 | F0 | | Keyboard Keypad 1 | F1 | | Keyboard Keypad 2 | F2 | | Keyboard Keypad 3 | F3 | | Keyboard Keypad 4 | F4 | | Keyboard Keypad 5 | F5 | | Keyboard Keypad 6 | F6 | | Keyboard Keypad 7 | F7 | | Keyboard Keypad 8 | F8 | | Keyboard Keypad 9 | F9 | | Keyboard Keypad Period . | FDOT | | Keyboard Keypad Enter | SMALL_ENTER | | Keyboard Up | CURSOR_UP | | Keyboard Down | CURSOR_DOWN | | Keyboard Right | CURSOR_RIGHT | | Keyboard Left | CURSOR_LEFT | | Keyboard Insert | JOY_FIRE1 | | Keyboard Home | JOY_UP | | Keyboard End | JOY_DOWN | | Keyboard Page Up | JOY_FIRE2 | | Keyboard Page Down | JOY_RIGHT | | Keyboard Caps Lock | CAPS_LOCK | | Keyboard Right Shift | SHIFT | | Keyboard Left Shift | SHIFT | | Keyboard Right Control | CONTROL | | Keyboard Left Control | CONTROL | ## External Links - [Official CrocoDS Github Repository](https://github.com/redbug26/crocods-core) - [Libretro CrocoDS Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/crocods_libretro.info) - [Libretro CrocoDS Github Repository](https://github.com/libretro/libretro-crocods) - [Report Libretro CrocoDS Core Issues Here](https://github.com/libretro/libretro-crocods/issues) ### See also #### Amstrad - CPC - [Amstrad - CPC (Caprice32)](caprice32.md) ================================================ FILE: docs/library/desmume.md ================================================ # Nintendo - DS (DeSmuME) ## Background DeSmuME is a Nintendo DS emulator [http://desmume.org](http://desmume.org) ### Author/License The DeSmuME core has been authored by - YopYop156 - Zeromus The DeSmuME core is licensed under - [GPLv2](https://github.com/TASVideos/desmume/blob/master/license.txt) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the DeSmuME core have the following file extensions: - .nds - .bin ## Databases RetroArch database(s) that are associated with the DeSmuME core: - [Nintendo - Nintendo DS](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%20DS.rdb) - [Nintendo - Nintendo DS Decrypted](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%20DS%20Decrypted.rdb) - [Nintendo - Nintendo DS (Download Play)](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%20DS%20(Download%20Play).rdb) ## BIOS Required or optional firmware files go in the frontend's `system` directory. !!! warning In order for the firmware files to be loaded by the DeSmuME core, the 'Use External BIOS/Firmware (restart)' core option must be set to enabled. The md5sum of firmware.bin will vary from dump to dump. bios7 and bios9 should be the exact same as here. firmware.bin may not be the same. | Filename | Description | md5sum | |:------------:|:-----------------------:|:--------------------------------:| | bios7.bin | ARM7 BIOS - Optional | df692a80a5b1bc90728bc3dfc76cd948 | | bios9.bin | ARM9 BIOS - Optional | a392174eb3e572fed6447e956bde4b25 | | firmware.bin | NDS Firmware - Optional | | ## Features Frontend-level settings or features that the DeSmuME core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ (Not Download Play, Link-Cable or Wi-Fi emulation) | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✔ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The DeSmuME core's library name is 'DeSmuME' The DeSmuME core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:------------:|:----------------------:| | *.dsv | Cartridge battery save | | firmware.dfc | Firmware settings save | **Frontend's State directory** | File | Description | |:-------:|:-----------:| | *.state | State | ### Geometry and timing - The DeSmuME core's core provided FPS is 60 - The DeSmuME core's core provided sample rate is 44100 Hz - The DeSmuME core's base width is dependent on the ['Screen layout' core option](#core-options). - The DeSmuME core's base height is dependent on the ['Screen layout' core option](#core-options). - The DeSmuME core's max width is dependent on the ['Screen layout' core option](#core-options). - The DeSmuME core's max height is dependent on the ['Screen layout' core option](#core-options). - The DeSmuME core's core provided aspect ratio is dependent on the ['Screen layout' core option](#core-options). ## Nickname The Nintendo DS' system nickname can be configured via RetroArch's Username setting in the User Menu. ## Core options The DeSmuME core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Firmware Language** [desmume_firmware_language] (**Auto**|English|Japanese|French|German|Italian|Spanish) Choose the language of the firmware. - **Use External BIOS/Firmware (restart)** [desmume_use_external_bios] (**disabled**|enabled) When set to enabled, the DeSmuME core will use the external firmware files found in RetroArch's System Directory. Look at the [BIOS section](#bios) for more information. - **Boot Into BIOS (interpreter and external bios only)** [desmume_boot_into_bios] (**disabled**|enabled) **For proper functionality of this core option. The 'CPU Mode' core option must be set to interpreter and the 'Use External BIOS/Firmware' core option must be set to enabled.** **Also, you must have external firmware files in RetroArch's System Directory.** When set to enabled, the DeSmuME core will boot into the Nintendo DS firmware screen upon content load. Any settings changed in the firmware screen will be saved to firmware.dfc in RetroArch's Save directory. - **Load Game Into Memory (restart)** [desmume_load_to_memory] (**disabled**|enabled) Loads the entire game into memory before startup. Will decrease in-game loading times at the cost of increased game startup times. - **CPU Cores** [desmume_num_cores] (**1**|2|3|4) Configure how many CPU cores the DeSmuME core will use. Please note that, in general, DeSmuME benefits more from few fast CPUs than from many slow CPUs. For example, a dual-core 3.9GHz CPU will run DeSmuME much faster than a 12-core 1.6GHz CPU. - **CPU Mode** [desmume_cpu_mode] (**jit**|interpreter) Choose to run CPU emulation through the Interpreter engine or the JIT Dynamic Recomplier engine. Interpreter has better compatibility than JIT Dynamic Recompiler. Some games that fail when using JIT Dynamic Recompiler will work fine with Interpreter. The tradeoff here is that Interpreter has much lower performance than JIT Dynamic Recompiler. Please note that the default setting for this core option is dependent on your hardware. The JIT Dynamic Recompiler is not available on all hardware (e.g. Android devices). - **JIT Block Size** [desmume_jit_block_size] (**12**|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59|60|61|62|63|64|65|66|67|68|69|70|71|72|73|74|75|76|77|78|79|80|81|82|83|84|85|86|87|88|89|90|91|92|93|94|95|96|97|98|99|100|0|1|2|3|4|5|6|7|8|9|10|11) This core option is only available when the 'CPU mode' core option to set to jit. You may need to tune the block size to prevent some games from breaking. 1 = most accurate, 100 = fastest. - **Enable Advanced Bus-Level Timing** [desmume_advanced_timing] (**enabled**|disabled) This will improve or fix some games but it is very performance demanding. Disable this if you want more speed. - **Frameskip** [desmume_frameskip] (**0**|1|2|3|4|5|6|7|8|9) Choose how much frames should be skipped to improve performance at the expense of visual smoothness. It is generally safe to choose 1 or 2 if you don't mind a slightly choppier game, in order to get a speedup. If screens seem stuck or screen flickering becomes unacceptable, pick a different frame skip value. - **Internal Resolution (restart)** [desmume_internal_resolution] (**256x192**|512x384|768x576|1024x768|1280x960|1536x1152|1792x1344|2048x1536|2304x1728|2560x1920) Configure the resolution. Requires a restart. ??? note "Internal resolution - 256x192" ![](../image/core/desmume/256x192.png) ??? note "Internal resolution - 2560x1920" ![](../image/core/desmume/2560x1920.png) - **OpenGL Rasterizer (restart)** [desmume_opengl_mode] (**disabled**|enabled) Enable OpenGL renderer. **The Frontend's video driver must be set to gl.** - **OpenGL: Color Depth (restart)** [desmume_color_depth] (**16-bit**|32-bit) 32-bit allows full color support from the DS (natively 6-bit). **OpenGL Rasterizer core option must be set to enabled.** - **OpenGL: Multisampling (restart)** [desmume_gfx_multisampling] (**disabled**|2|4|8|16|32) Awaiting description. - **OpenGL: Texture Smoothing** [desmume_gfx_texture_smoothing] (**disabled**|enabled) Awaiting description. - **Soft3D: High-res Color Interpolation** [desmume_gfx_highres_interpolate_color] (**disabled**|enabled) Awaiting description. - **Soft3D: Line Hack** [desmume_gfx_linehack] (**enabled**|disabled) Fixes some graphical bugs involving lines, but causes some other bugs. Not many games use lines. - **Soft3D: Texture Hack** [desmume_gfx_txthack] (**disabled**|enabled) Awaiting description. - **Edge Marking** [desmume_gfx_edgemark] (**enabled**|disabled) Awaiting description. - **"Texture Scaling (xBrz)** [desmume_gfx_texture_scaling] (**1**|2|4) Awaiting description. - **Texture Deposterization** [desmume_gfx_texture_deposterize] (**disabled**|enabled) Awaiting description. - **Screen Layout** [desmume_screens_layout] (**top/bottom**|bottom/top|left/right|right/left|top only|bottom only|quick switch|hybrid/top|hybrid/bottom) Self-explanatory. ??? note "Screen layout - top/bottom" ![](../image/core/desmume/top_bottom.png) ??? note "Screen layout - bottom/top" ![](../image/core/desmume/bottom_top.png) ??? note "Screen layout - left/right" ![](../image/core/desmume/left_right.png) ??? note "Screen layout - right/left" ![](../image/core/desmume/right_left.png) ??? note "Screen layout - top only" ![](../image/core/desmume/top.png) ??? note "Screen layout - bottom only" ![](../image/core/desmume/bottom.png) ??? note "Screen layout - hybrid/top" ![](../image/core/desmume/hybrid_top.png) - **Screen Gap** [desmume_screens_gap] (0 to 100 in increments of 1. **0 is default.**) Self explanatory. ??? note "Screen Gap - 0" ![](../image/core/desmume/screengap_0.png) ??? note "Screen Gap - 100" ![](../image/core/desmume/screengap_100.png) - **Hybrid Layout: Scale (restart)** [desmume_hybrid_layout_scale] (**1**|3) Self explanatory. The 'Screen layout' core option must be set to a hybrid setting for this to function properly. ??? note "Hybrid layout scale - 1" ![](../image/core/desmume/scale_1.png) ??? note "Hybrid layout scale - 3" ![](../image/core/desmume/scale_3.png) - **Hybrid Layout: Show Both Screens** [desmume_hybrid_showboth_screens] (**enabled**|disabled) Removes the small top screen when the 'Screen layout' core option is set to hybrid/top Removes the small bottom screen when the 'Screen layout' core option is set to hybrid/bottom - **Hybrid Layout: Cursor Always on Small Screen** [desmume_hybrid_cursor_always_smallscreen] (**enabled**|disabled) Self explanatory. Disablng this allows you to use the stylus on the big bottom screen when the 'Screen layout' core option is set to hybrid/bottom. - **Mouse/Pointer** [desmume_pointer_mouse] (**enabled**|disabled) Enabling this allows inputs for the stylus. - **Pointer Type** [desmume_pointer_type] (**mouse**|touch) Setting this to mouse allows you to use mouse inputs for the stylus Setting this to touch allows you to use mouse/touch inputs for the stylus (e.g. Touch controls on Android devices). - **Mouse Speed** [desmume_mouse_speed] (**1.0**|1.5|2.0|0.01|0.02|0.03|0.04|0.05|0.125|0.25|0.5) **The Pointer type core option must be set to mouse** Adjust mouse speed for the stylus. - **Pointer Rotation** [desmume_input_rotation] (**0**|90|180|270) Rotate pointer controls This is can be used in conjuction with RetroArch's Rotation setting. - **Pointer Mode for Left Analog** [desmume_pointer_device_l] (**none**|emulated|absolute|pressed) Awaiting description. - **Pointer Mode for Right Analog** [desmume_pointer_device_r] (**none**|emulated|absolute|pressed) Awaiting description. - **Emulated Pointer Deadzone Percent** [desmume_pointer_device_deadzone] (**15**|20|25|30|35|0|5|10") Awaiting description. - **Emulated Pointer Acceleration Modifier Percent** [desmume_pointer_device_acceleration_mod] (**0**|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59|60|61|62|63|64|65|66|67|68|69|70|71|72|73|74|75|76|77|78|79|80|81|82|83|84|85|86|87|88|89|90|91|92|93|94|95|96|97|98|99|100) Awaiting description. - **Emulated Stylus Pressure Modifier Percent** [desmume_pointer_stylus_pressure] (**50**|51|52|53|54|55|56|57|58|59|60|61|62|63|64|65|66|67|68|69|70|71|72|73|74|75|76|77|78|79|80|81|82|83|84|85|86|87|88|89|90|91|92|93|94|95|96|97|98|99|100|0|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49) Awaiting description. - **Pointer Colour** [desmume_pointer_colour] (**white**|black|red|blue|yellow) Awaiting description. - **Microphone Button Noise Type** [desmume_mic_mode] (**pattern**|random) Configure microphone input settings. With the pattern setting, DeSmuME will use its internal noise sample for microphone input which works for many games that want you to blow on the mic. With the random setting, DeSmuME will use random whitenoise for microphone input which will work for games that require blowing but which don't work with the internal noise sample. ## Controllers The DeSmuME core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. There's no reason to switch to this. - **RetroPad** - Joypad - Stay on this. - RetroPad w/Analog - Joypad - Same as RetroPad. There's no reason to switch to this. ### Other controllers - Stylus - Pointer or Mouse - The DesmuME 2015 core will emulate stylus inputs using the mouse API or the pointer API depending on what the ['Pointer type' core option](#core-options) is set to. ### Device tables #### Joypad ![](../image/controller/nds.png) | User 1 input descriptors | RetroPad Inputs | DeSmuME inputs | |--------------------------|------------------------------------------------|---------------------| | B | ![](../image/retropad/retro_b.png) | B | | Y | ![](../image/retropad/retro_y.png) | Y | | Select | ![](../image/retropad/retro_select.png) | Select | | Start | ![](../image/retropad/retro_start.png) | Start | | Up | ![](../image/retropad/retro_dpad_up.png) | Up | | Down | ![](../image/retropad/retro_dpad_down.png) | Down | | Left | ![](../image/retropad/retro_dpad_left.png) | Left | | Right | ![](../image/retropad/retro_dpad_right.png) | Right | | A | ![](../image/retropad/retro_a.png) | A | | X | ![](../image/retropad/retro_x.png) | X | | L | ![](../image/retropad/retro_l1.png) | L | | R | ![](../image/retropad/retro_r1.png) | R | | Lid Close/Open | ![](../image/retropad/retro_l2.png) | Lid Close/Open | | Tap Stylus | ![](../image/retropad/retro_r2.png) | Tap Stylus | | Make Microphone Noise | ![](../image/retropad/retro_l3.png) | Toggle Microphone | | Quick Screen Switch | ![](../image/retropad/retro_r3.png) | Quick Screen Switch | | | ![](../image/retropad/retro_left_stick.png) X | [Pointer mode l-analog](#core-options) X | | | ![](../image/retropad/retro_left_stick.png) Y | [Pointer mode l-analog](#core-options) Y | | | ![](../image/retropad/retro_right_stick.png) X | [Pointer mode r-analog](#core-options) X | | | ![](../image/retropad/retro_right_stick.png) Y | [Pointer mode r-analog](#core-options) Y | #### Mouse | RetroMouse Inputs | DeSmuME inputs | |-------------------------------------------------------|----------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Stylus | | ![](../image/retromouse/retro_left.png) Mouse 1 | Stylus Press | #### Pointer | RetroPointer Inputs | DeSmuME inputs | |--------------------------------------------------------------------------------------------------------------------------|----------------| | ![](../image/retromouse/retro_mouse.png) or ![](../image/Button_Pack/Gestures/Gesture_Finger_Front.png) Pointer Position | Stylus | | ![](../image/retromouse/retro_left.png) or ![](../image/Button_Pack/Gestures/Gesture_Tap.png) Pointer Pressed | Stylus Press | ## Compatibility Same as upstream standalone. ## External Links - [Official DeSmuME Website](https://desmume.org/) - [Official DeSmuME Github Repository](https://github.com/TASVideos/desmume) - [Libretro DeSmuME Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/desmume_libretro.info) - [Libretro DeSmuME Github Repository](https://github.com/libretro/desmume) - [Report Libretro DeSmuME Core Issues Here](https://github.com/libretro/desmume/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0Icim_vEjB_0GeF18zkMBiqU) ### See also #### Nintendo - Nintendo DS + Decrypted + (Download Play) - [Nintendo - DS (DeSmuME 2015)](desmume_2015.md) - [Nintendo - DS (melonDS 2021)](melonds.md) - [Nintendo - DS (melonDS DS)](melonds_ds.md) ================================================ FILE: docs/library/desmume_2015.md ================================================ # Nintendo - DS (DeSmuME 2015) ## Background Port of Desmume to libretro based on Desmume SVN circa 2015. ### Author/License The DeSmuME 2015 core has been authored by - YopYop156 - Zeromus The DeSmuME 2015 core is licensed under - [GPLv2](https://github.com/libretro/desmume2015/blob/master/desmume/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the DeSmuME 2015 core have the following file extensions: - .nds - .bin ## Databases RetroArch database(s) that are associated with the DeSmuME 2015 core: - [Nintendo - Nintendo DS](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%20DS.rdb) - [Nintendo - Nintendo DS Decrypted](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%20DS%20Decrypted.rdb) - [Nintendo - Nintendo DS (Download Play)](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%20DS%20(Download%20Play).rdb) ## Features Frontend-level settings or features that the DeSmuME 2015 core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ (Not Download Play, Link-Cable or Wi-Fi emulation) | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The DeSmuME 2015 core's library name is 'DeSmuME 2015' The DeSmuME 2015 core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:----------------------:| | *.dsv | Cartridge battery save | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ### Geometry and timing - The DeSmuME 2015 core's core provided FPS is 60 - The DeSmuME 2015 core's core provided sample rate is 44100 Hz - The DeSmuME 2015 core's base width is dependent on the ['Screen layout' core option](#core-options). - The DeSmuME 2015 core's base height is dependent on the ['Screen layout' core option](#core-options). - The DeSmuME 2015 core's max width is dependent on the ['Screen layout' core option](#core-options). - The DeSmuME 2015 core's max height is dependent on the ['Screen layout' core option](#core-options). - The DeSmuME 2015 core's core provided aspect ratio is dependent on the ['Screen layout' core option](#core-options). ## Nickname Changing the system nickname isn't currently supported by the DeSmuME 2015 core. ## Core options The DeSmuME 2015 core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Internal resolution (restart)** [desmume_internal_resolution] (**256x192**|512x384|768x576|1024x768|1280x960|1536x1152|1792x1344|2048x1536|2304x1728|2560x1920) Self explanatory. Please note that the DeSmuME core is only software rendered. ??? note "Internal resolution - 256x192" ![](../image/core/desmume/256x192.png) ??? note "Internal resolution - 2560x1920" ![](../image/core/desmume/2560x1920.png) - **CPU cores** [desmume_num_cores] (**1**|2|3|4) Configure how much CPU cores the DeSmuME core will use. Please note that, in general, DeSmuME benefits more from few fast CPUs than from many slow CPUs. For example, a dual-core 3.9GHz CPU will run DeSmuME much faster than a 12-core 1.6GHz CPU. - **CPU mode** [desmume_cpu_mode] (**jit**|interpreter) Choose to run CPU emulation through the Interpreter engine or the JIT Dynamic Recomplier engine. Interpreter has better compatibility than JIT Dynamic Recompiler. Some games that fail when using JIT Dynamic Recompiler will work fine with Interpreter. The tradeoff here is that Interpreter has much lower performance than JIT Dynamic Recompiler. Please note that the default setting for this core option is dependent on your hardware. The JIT Dynamic Recompiler is not available on all hardware (e.g. Android devices). - **JIT block size** [desmume_jit_block_size] (0 to 100 in increments of 1. **12 is default**.) This core option is only available when the 'CPU mode' core option to set to jit. You may need to tune the block size to prevent some games from breaking. 1 = most accurate, 100 = fastest. - **Screen layout** [desmume_screens_layout] (**top/bottom**|bottom/top|left/right|right/left|top only|bottom only|quick switch|hybrid/top|hybrid/bottom) Self-explanatory. ??? note "Screen layout - top/bottom" ![](../image/core/desmume/top_bottom.png) ??? note "Screen layout - bottom/top" ![](../image/core/desmume/bottom_top.png) ??? note "Screen layout - left/right" ![](../image/core/desmume/left_right.png) ??? note "Screen layout - right/left" ![](../image/core/desmume/right_left.png) ??? note "Screen layout - top only" ![](../image/core/desmume/top.png) ??? note "Screen layout - bottom only" ![](../image/core/desmume/bottom.png) ??? note "Screen layout - hybrid/top" ![](../image/core/desmume/hybrid_top.png) - **Hybrid layout scale (restart)** [desmume_hybrid_layout_scale] (**1**|3) Self explanatory. The 'Screen layout' core option must be set to a hybrid setting for this to function properly. ??? note "Hybrid layout scale - 1" ![](../image/core/desmume/scale_1.png) ??? note "Hybrid layout scale - 3" ![](../image/core/desmume/scale_3.png) - **Hybrid layout show both screen** [desmume_hybrid_showboth_screens] (**enabled**|disabled) Removes the small top screen when the 'Screen layout' core option is set to hybrid/top Removes the small bottom screen when the 'Screen layout' core option is set to hybrid/bottom - **Hybrid layout cursor always on small screen** [desmume_hybrid_cursor_always_smallscreen] (**enabled**|disabled) Self explanatory. Disablng this allows you to use the stylus on the big bottom screen when the 'Screen layout' core option is set to hybrid/bottom. - **Enable mouse/pointer** [desmume_pointer_mouse] (**enabled**|disabled) Enabling this allows inputs for the stylus. - **Pointer type** [desmume_pointer_type] (**mouse**/touch) Setting this to mouse allows you to use mouse inputs for the stylus Setting this to touch allows you to use mouse/touch inputs for the stylus (e.g. Touch controls on Android devices). - **Mouse Speed** [desmume_mouse_speed] (**1.0**|1.5|2.0|0.125|0.25|0.5) **The Pointer type core option must be set to mouse** Adjust mouse speed for the stylus. - **Pointer Colour** [desmume_pointer_colour] (**white**|black|red|blue|yellow") Configure the color of the stylus pointer. ??? note "Pointer Colour - white" ![](../image/core/desmume/pointer_white.png) ??? note "Pointer Colour - black" ![](../image/core/desmume/pointer_black.png) ??? note "Pointer Colour - red" ![](../image/core/desmume/pointer_red.png) ??? note "Pointer Colour - blue" ![](../image/core/desmume/pointer_blue.png) ??? note "Pointer Colour - yellow" ![](../image/core/desmume/pointer_yellow.png) - **Pointer mode l-analog** [desmume_pointer_device_l] (**none**|emulated|absolute|pressed) Awaiting description. - **Pointer mode r-analog** [desmume_pointer_device_r] (**none**|emulated|absolute|pressed) Awaiting description. - **Emulated pointer deadzone percent** [desmume_pointer_device_deadzone] (**15**|20|25|30|35|0|5|10) Awaiting description. - **Emulated pointer acceleration modifier percent** [desmume_pointer_device_acceleration_mod] (0 to 100 in increments of 1. **0 is default**.) Awaiting description. - **Emulated stylus pressure modifier percent** [desmume_pointer_stylus_pressure] (0 to 100 in increments of 1. **50 is default**.) Configure the emulated pressure on the touchscreen from a stylus pressing on it. - **Enable emulated stylus jitter** [desmume_pointer_stylus_jitter] (**disabled**|enabled) Emulate the tiny jitter from a human hand when holding a stylus; some games were accidentally dependent on this. - **Load Game into Memory (restart)** [desmume_load_to_memory] (**disabled**|enabled) Loads the entire game into memory before startup. Will decrease in-game loading times at the cost of increased game startup times. - **Enable Advanced Bus-Level Timing** [desmume_advanced_timing] (**enabled**|disabled) This will improve or fix some games but it is very performance demanding. Disable this if you want more speed. - **Firmware language** [desmume_firmware_language] (**Auto**|English|Japanese|French|German|Italian|Spanish) Choose the language of the BIOS. - **Frameskip** [desmume_frameskip] (**0**|1|2|3|4|5|6|7|8|9) Choose how much frames should be skipped to improve performance at the expense of visual smoothness. It is generally safe to choose 1 or 2 if you don't mind a slightly choppier game, in order to get a speedup. If screens seem stuck or screen flickering becomes unacceptable, pick a different frame skip value. - **Screen Gap** [desmume_screens_gap] (0 to 100 in increments of 1. **0 is default.**) Self explanatory. ??? note "Screen Gap - 0" ![](../image/core/desmume/screengap_0.png) ??? note "Screen Gap - 100" ![](../image/core/desmume/screengap_100.png) - **Enable Edgemark** [desmume_gfx_edgemark] (**enabled**|disabled) Awaiting description. - **Enable Line Hack** [desmume_gfx_linehack] (**enabled**|disabled) Fixes some graphical bugs involving lines, but causes some other bugs. Not many games use lines. - **Enable TXT Hack** [desmume_gfx_txthack] (**disabled**|enabled) Fixes text bugs in some games (e.g. Etrian Odyssey). You may need to toggle it off & on by scene. - **Force Microphone Enable** [desmume_mic_force_enable] (**disabled**|enabled) Self-explanatory. - **Microphone Simulation Settings** [desmume_mic_mode] (**internal**|sample|random|physical) Configure microphone input settings. With the internal setting, DeSmuME will use its internal noise sample for microphone input which works for many games that want you to blow on the mic. With the sample setting, you can supply your own microphone sample for microphone input. **This may not work currently in the DeSmuME core**. With the random setting, DeSmuME will use random whitenoise for microphone input which will work for games that require blowing but which don't work with the internal noise sample. With the physical setting, you can use your default recording device for microphone input. **This may not work currently in the DeSmuME core**. ## Controllers The DeSmuME 2015 core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. There's no reason to switch to this. - **RetroPad** - Joypad - Stay on this. - RetroPad w/Analog - Joypad - Same as RetroPad. There's no reason to switch to this. ### Other devices - Stylus - Pointer or Mouse - The DesmuME 2015 core will emulate stylus inputs using the mouse API or the pointer API depending on what the ['Pointer type' core option](#core-options) is set to. ### Device tables #### Joypad ![](../image/controller/nds.png) | User 1 input descriptors | RetroPad Inputs | DeSmuME 2015 inputs | |--------------------------|------------------------------------------------|---------------------| | B | ![](../image/retropad/retro_b.png) | B | | Y | ![](../image/retropad/retro_y.png) | Y | | Select | ![](../image/retropad/retro_select.png) | Select | | Start | ![](../image/retropad/retro_start.png) | Start | | Up | ![](../image/retropad/retro_dpad_up.png) | Up | | Down | ![](../image/retropad/retro_dpad_down.png) | Down | | Left | ![](../image/retropad/retro_dpad_left.png) | Left | | Right | ![](../image/retropad/retro_dpad_right.png) | Right | | A | ![](../image/retropad/retro_a.png) | A | | X | ![](../image/retropad/retro_x.png) | X | | L | ![](../image/retropad/retro_l1.png) | L | | R | ![](../image/retropad/retro_r1.png) | R | | Lid Close/Open | ![](../image/retropad/retro_l2.png) | Lid Close/Open | | Tap Stylus | ![](../image/retropad/retro_r2.png) | Tap Stylus | | Toggle Microphone | ![](../image/retropad/retro_l3.png) | Toggle Microphone | | Quick Screen Switch | ![](../image/retropad/retro_r3.png) | Quick Screen Switch | | | ![](../image/retropad/retro_left_stick.png) X | [Pointer mode l-analog](#core-options) X | | | ![](../image/retropad/retro_left_stick.png) Y | [Pointer mode l-analog](#core-options) Y | | | ![](../image/retropad/retro_right_stick.png) X | [Pointer mode r-analog](#core-options) X | | | ![](../image/retropad/retro_right_stick.png) Y | [Pointer mode r-analog](#core-options) Y | #### Mouse | RetroMouse Inputs | DeSmuME 2015 inputs | |-------------------------------------------------------|---------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Stylus | | ![](../image/retromouse/retro_left.png) Mouse 1 | Stylus Press | #### Pointer | RetroPointer Inputs | DeSmuME 2015 inputs | |--------------------------------------------------------------------------------------------------------------------------|---------------------| | ![](../image/retromouse/retro_mouse.png) or ![](../image/Button_Pack/Gestures/Gesture_Finger_Front.png) Pointer Position | Stylus | | ![](../image/retromouse/retro_left.png) or ![](../image/Button_Pack/Gestures/Gesture_Tap.png) Pointer Pressed | Stylus Press | ## Compatibility | Game | Issue | |------------------------------------------|-----------------------------------------------------------------------------------------------| | Alice in Wonderland | Needs JIT Block Size 8 or smaller to get past title screen. | | Golden Sun: Dark Dawn (Europe) | Runs very slowly. Buggy sound. | | Hotel Dusk: Room 215 | Graphics glitches. Unintended "scanlines" appear on some screens. | | Pokémon HeartGold (Europe) (Rev 10) | Graphics glitches . Black pixels pop-ups in the top screen. Top screen goes black. | | Pokémon SoulSilver (Europe) (Rev 10) | Graphics glitches. Black pixels pop-ups in the top screen. Top screen goes black. | | Puppy Palace (U) / My Puppy Shop (E) | Crashes in menus. | | Rune Factory (U) | Random crashes. | | Rune Factory 2 (U) | Random crashes. | | Ultimate Mortal Kombat 3 | Runs very slowly. | | Yoshi Touch & Go | Runs very slowly. | | Yu-Gi-Oh! 5D's WORLD CHAMPIONSHIP 2010 (J) | Random crashes. | ## External Links - [Official DeSmuME Website](https://desmume.org/) - [Official DeSmuME Github Repository](https://github.com/TASVideos/desmume) - [Libretro DeSmuME 2015 Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/desmume2015_libretro.info) - [Libretro DeSmuME 2015 Github Repository](https://github.com/libretro/desmume2015) - [Report Libretro DeSmuME 2015 Core Issues Here](https://github.com/libretro/desmume2015/issues) ### See also #### Nintendo - Nintendo DS (Download Play) - [Nintendo - DS (DeSmuME)](desmume.md) - [Nintendo - DS (melonDS 2021)](melonds.md) - [Nintendo - DS (melonDS DS)](melonds_ds.md) #### Nintendo - Nintendo DS Decrypted - [Nintendo - DS (DeSmuME)](desmume.md) - [Nintendo - DS (melonDS 2021)](melonds.md) - [Nintendo - DS (melonDS DS)](melonds_ds.md) #### Nintendo - Nintendo DS - [Nintendo - DS (DeSmuME)](desmume.md) - [Nintendo - DS (melonDS 2021)](melonds.md) - [Nintendo - DS (melonDS DS)](melonds_ds.md) ================================================ FILE: docs/library/dice.md ================================================ # DICE ## Background DICE is a Discrete Integrated Circuit Emulator. It emulates computer systems that lack any type of CPU, consisting only of discrete logic components. dice-libretro is a Libretro port of DICE, to run in RetroArch. The DICE core has been authored by: - Adam B & DICE Team (Standalone DICE) - Ken Mitton The DICE core is licensed under: - [GPLv3](https://github.com/mittonk/dice-libretro/blob/main/LICENSE.txt) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Requirements Minimal. ## How to start the DICE core: Some games use zipped ROMs and launch similarly to MAME or FBNeo --- filename is important, see table at https://github.com/mittonk/dice-libretro/?tab=readme-ov-file#usage Please do not attempt to contact the DICE team to request ROM files. Some games (pong, breakout, pinpong, etc) do not have any ROM on the board at all. For these, copy the dummy launcher file from [dummy_files](https://github.com/mittonk/dice-libretro/tree/main/dummy_files) to your ROM folder; these have a correct name (for example, pong.dmy) that will get RetroArch to set up lr-dice for the correct game. ## BIOS None. ## Extensions Content that can be loaded by the DICE core have the following file extensions: - .zip - .dmy .dmy files are used for games without any ROM component, see "How to start the DICE core" above. RetroArch database(s) that are associated with the DICE core: - [DICE](https://github.com/libretro/libretro-database/blob/master/rdb/DICE.rdb) ## Features Frontend-level settings or features that the DICE core respects: | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✕ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✔ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✔ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Directories None. ## Geometry and timing Varies based on individual game, mostly around 640x246, 60 FPS. ## Usage Again, see .dmy files for games that do not use read-only memory. ## Core options There are numerous options around using mice to simulate spinners / paddle controllers, see [mouse-support](https://github.com/mittonk/dice-libretro/?tab=readme-ov-file#mouse-support). - Easy: One mouse can be used for Paddle 1. Use "Core Options -> Use mouse pointer for paddle 1". You'll still want a keyboard or gamepad handy to have enough buttons. - Somewhat advanced: Multiple mice are supported using certain libretro drivers on Linux and Windows, see [retromouse.md](https://github.com/mittonk/dice-libretro/blob/main/retromouse.md). ## User 1 device types The DICE core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): - **RetroPad** - RetroPad w/Analog - Mouse ## Joypad Most games are playable with just a joypad. Controls vary by game. | RetroPad Inputs | User # input descriptors | (Device name) Inputs | |------------------------------------------------|--------------------------|---------------------------| | ![](../image/retropad/retro_b.png) | Button 1 | - | | ![](../image/retropad/retro_y.png) | Button 3 | - | | ![](../image/retropad/retro_select.png) | Coin | - | | ![](../image/retropad/retro_start.png) | Start | - | | ![](../image/retropad/retro_dpad_up.png) | Up | - | | ![](../image/retropad/retro_dpad_down.png) | Down | - | | ![](../image/retropad/retro_dpad_left.png) | Left | - | | ![](../image/retropad/retro_dpad_right.png) | Right | - | | ![](../image/retropad/retro_a.png) | Button 2 | - | | ![](../image/retropad/retro_x.png) | | - | | ![](../image/retropad/retro_l1.png) | Dollar | - | | ![](../image/retropad/retro_r1.png) | | - | | ![](../image/retropad/retro_l2.png) | | - | | ![](../image/retropad/retro_r2.png) | | - | | ![](../image/retropad/retro_l3.png) | | - | | ![](../image/retropad/retro_r3.png) | | - | | ![](../image/retropad/retro_left_stick.png) X | Paddle | - | | ![](../image/retropad/retro_left_stick.png) Y | Paddle | - | | ![](../image/retropad/retro_right_stick.png) X | | - | | ![](../image/retropad/retro_right_stick.png) Y | | - | ## Mouse | RetroMouse Inputs | (Device name) Inputs | |-------------------------------------------------------|---------------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Paddle, see [mouse-support](https://github.com/mittonk/dice-libretro/?tab=readme-ov-file#mouse-support) | | ![](../image/retromouse/retro_left.png) Mouse 1 | - | | ![](../image/retromouse/retro_right.png) Mouse 2 | - | | ![](../image/retromouse/retro_middle.png) Mouse 3 | - | | Mouse 4 | - | | Mouse 5 | - | | Wheel Up | - | | Wheel Down | - | | Wheel Left | - | | Wheel Right | - | ## Compatibility | Name | Base filename | Publisher | Year | Needs ROM? | | ---- | ------------- | --------- | ---- | -------- | | Anti-Aircraft | antiaircraft | Atari | 1975 | x | | Attack | attack | Exidy | 1977 | x | | Breakout | breakout | Atari | 1976 | | | Clean Sweep | cleansweep | Ramtek | 1974 | x | | Crash 'N Score | crashnscore | Atari | 1975 | x | | Crossfire | crossfire | Atari | 1975 | | | Gotcha | gotcha | Atari | 1973 | | | Hi-Way | hiway | Atari | 1975 | | | Indy 4 | indy4 | Atari | 1976 | x | | Jet Fighter | jetfighter | Atari | 1975 | x | | Pin Pong | pinpong | Atari | 1974 | | | Pong | pong | Atari | 1972 | | | Pong Doubles | pongdoubles | Atari | 1973 | | | Quadrapong | quadrapong | Atari | 1974 | | | Rebound | rebound | Atari | 1974 | | | Shark Jaws | sharkjaws | Atari | 1975 | x | | Space Race | spacerace | Atari | 1973 | | | Steeplechase | steeplechase | Atari | 1975 | x | | Stunt Cycle | stuntcycle | Atari | 1976 | x | | TV Basketball | tvbasketball | Midway | 1974 | | | Wipe Out | wipeout | Ramtek | 1974 | x | ## External Links - [Original DICE Website](https://adamulation.blogspot.com/) (inactive) - [Original DICE Repository](https://sourceforge.net/projects/dice/) (inactive) - [DirtBagXon's DICE Repository](https://github.com/DirtBagXon/DICE) - [Libretro DICE Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/dice.info) - [Libretro DICE Github Repository](https://github.com/mittonk/dice-libretro) - [Report Libretro DICE Core Issues Here](https://github.com/mittonk/dice-libretro/issues) ## (Related cores) MAME has some overlap (Pong, for example). ================================================ FILE: docs/library/dinothawr.md ================================================ # Dinothawr ## Background Dinothawr is a block pushing puzzle game on slippery surfaces. Our hero is a dinosaur whose friends are trapped in ice. Through puzzles it is your task to free the dinos from their ice prison. The Dinothawr core has been authored by - Themaister (programming, music, some level design) - Runar Heyer (art, level design, some code) The Dinothawr core is licensed under - [Non-commercial](https://github.com/libretro/Dinothawr/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Setup - To start the Dinothawr core, you need to obtain Dinothawr's data files. You can do this by going to RetroArch's main menu screen and selecting 'Online Updater'. From there, select 'Content Downloader'.
![](../image/core/all/download.png)
- Select 'Dinothawr', then select 'Dinothawr.zip'. This should download and extract this file to RetroArch's Downloads directory.
![](../image/core/dinothawr/dinothawr.png)
- Go back to RetroArch's main menu screen. Select 'Load Content', then 'Downloads'.
![](../image/core/all/load.png)
![](../image/core/all/downloads.png)
- Select the 'dinothawr' directory, then select 'dinothawr.game'. - If you are asked which core to select, choose 'Dinothawr'. The content should now start running! ## Extensions Content that can be loaded by the Dinothawr core have the following file extensions: - .game ## Databases RetroArch database(s) that are associated with the Dinothawr core: - [Dinothawr](https://github.com/libretro/libretro-database/blob/master/rdb/Dinothawr.rdb) ## Features Frontend-level settings or features that the Dinothawr core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Dinothawr core's internal core name is 'Dinothawr' The Dinothawr core saves/loads to/from these directories. **Frontend's Save directory** - dinothawr.srm (Save data) ### Geometry and timing - The Dinothawr core's core provided FPS is (FPS) - The Dinothawr core's core provided sample rate is (Rate) - The Dinothawr core's core provided aspect ratio is (Ratio) ## Customizing / Hacking Dinothawr is fairly hackable. dinothawr.game is the game file itself. It is a simple XML file which points to all assets used by the game. Levels are organized in chapters. Levels themselves are created using the [Tiled](http://www.mapeditor.org/) editor. If you want to try making your own levels, make sure you use the "plain XML" format for .tmx files and not the default zlib base64. [Dinothawr - Level Design guide (pdf)](http://retinaleclipse.com/dinothawr-guide.pdf) ## Core options The Dinothawr core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Timer as FPS reference** [dino_timer] (**enabled**|disabled) Use timer as FPS reference. ## Controllers The Dinothawr core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. - **RetroPad** - Joypad - Stay on this. - RetroPad w/Analog - Joypad - There's no reason to switch to this. ## Joypad ![](http://themaister.net/dinothawr/shield.png) | User 1 Remap descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | Push | ![](../image/retropad/retro_b.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | Menu | ![](../image/retropad/retro_a.png) | | Reset | ![](../image/retropad/retro_x.png) | ## External Links - [Official/Libretro Dinothawr Github Repository](https://github.com/libretro/Dinothawr) - [Report Libretro Dinothawr Core Issues Here](https://github.com/libretro/Dinothawr/issues) - [Steam](https://store.steampowered.com/app/1222639/RetroArch__Dinothawr/) ================================================ FILE: docs/library/dolphin.md ================================================ # Nintendo Gamecube/Wii (Dolphin) ## Background A Nintendo Gamecube/Wii emulator for Android, Windows, Mac and Linux, written in C++. The dolphin-libretro core supports [OpenGL](#opengl), [Vulkan](#vulkan), and [Direct3D 11](#d3d11) rendering. The dolphin-libretro core is licensed under - [GPLv2](https://github.com/libretro/dolphin/blob/master/LICENSE.TXT) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Requirements - OpenGL/Open GL ES 3.0 or higher for the OpenGL renderer. - Vulkan for the Vulkan renderer. - Direct3D 11 for the Direct3D 11 renderer. ## Setup To function properly, the dolphin-libretro core requires the Dolphin `Sys` folder to be in the proper location. This directory contains Dolphin's database of per-game compatibility settings/hacks, without which many games experience bugs of varying severity. After downloading the core within RetroArch, do **one** of the following options: ### A. Installing from the 'Core System Files Downloader' (Easy/Automatic) If your frontend version has `Main Menu > Online Updater > Core System Files Downloader` then that's the easiest solution. Just download 'Dolphin.zip' from that menu and it will place the files where it needs them. You're all done! ### B. Installing from the GitHub repo (Hard/Manual) 1. Get a copy of the Dolphin `Sys` folder. This can be done by downloading the current source code. We provide two methods: one using *Git* and one without. * **If you have *Git* (if not, see the next option)** Just clone the most recent version of the code by running: ``` git clone --depth=1 https://github.com/libretro/dolphin.git ``` * **If you don't have *Git* ** You can download a *zip* file of the source code with the following URL: [https://github.com/libretro/dolphin/archive/master.zip](https://github.com/libretro/dolphin/archive/master.zip) You can then extract it. 2. After downloading/extracting the code, navigate into the resulting source tree folder. The `Sys` folder you need is located in *Data/Sys*. This is the folder we will need to move/copy. 3. *Find RetroArch's system folder path* If you didn't change its default location, the `system` folder is located at the top level of your RetroArch installation folder. Whether you moved it or not, you can find the location of your `system` folder (along with any other folders RetroArch uses) by going to Settings > Directory or by locating the *system_directory* line in the RetroArch configuration file (usually `retroarch.cfg`). 4. In the `RETROARCH_SYSTEM_FOLDER`, create a new folder named *dolphin-emu* and move/copy the `Sys` folder into it. When everything is set up properly, the `Sys` folder path should look something like this: ``` RETROARCH_SYSTEM_FOLDER/dolphin-emu/Sys ``` The dolphin-libretro core will now work much more reliably. ## BIOS The (optional) BIOS file goes in the directory `RETROARCH_SAVES_FOLDER/dolphin-emu/User/GC/`, with the file name `IPL.bin` for all regions. It is not necessary to provide a BIOS for most games, but certain titles (particularly those which make heavy use of the system fonts, like Star Fox Assault) can be unplayable without it. To play the [Gamecube BIOS animation](https://www.youtube.com/watch?v=CpmYW-gCSy4) at game launch, once you have the aforementioned BIOS file placed and named correctly, open the `Dolphin.ini` file located in `RETROARCH_SAVES_FOLDER/dolphin-emu/User/GameSettings/Config/` with a text editor and change the line `SkipIPL = True` to `SkipIPL = False`. ## Extensions Content that can be loaded by the dolphin-libretro core have the following file extensions: - .elf - .iso - .gcm - .dol - .tgc - .wbfs - .ciso - .gcz - .wad - .rvz RetroArch database(s) that are associated with the dolphin-libretro core: - [Nintendo - GameCube](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20GameCube.rdb) - [Nintendo - Wii](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Wii.rdb) ## Features Frontend-level settings or features that the dolphin-libretro core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✕ | | Native Cheats | ✔ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✔ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Directories In addition to the aforementioned `RETROARCH_SYSTEM_FOLDER/dolphin-emu` directory, the dolphin-libretro core also creates a folder structure similar to that used by the standalone Dolphin emulator in `RETROARCH_SAVES_FOLDER/dolphin-emu/User`. In this structure, you can access/edit most of the same functionality you would find in the standalone Dolphin emulator and can even copy some files--such as `GAME.ini` and save files--back and forth between the dolphin-libretro core and the standalone Dolphin emulator. ## Geometry and timing - The dolphin-libretro core's core provided FPS is 60 (for NTSC) / 50 (for PAL) - The dolphin-libretro core's core provided sample rate can be either 32000 Hz or 48000 Hz depending on user configuration - The dolphin-libretro core's base width is dependent on the 'Internal Resolution' core option - The dolphin-libretro core's base height is dependent on the 'Internal Resolution' core option - The dolphin-libretro core's max width is dependent on the 'Internal Resolution' core option - The dolphin-libretro core's max height is dependent on the 'Internal Resolution' core option - The dolphin-libretro core's core provided aspect ratio is 4/3. ## Language When the `Language` core option is set to automatic, the default dolphin-libretro language setting will be pulled from RetroArch's Language setting. ## Internal Cheats Disabled by default. Internal cheats can be handled via the GAME.ini files, but they will not take effect unless internal cheats are enabled in the core options. While there is no automatic way to add cheats to the dolphin-libretro core, it can use a cheat file generated by the standalone Dolphin emulator using the following process: 1. Open standalone Dolphin emulator and right-click your game > Properties. 2. Look at the title bar and remember the ID of the game (for example `GFZE01` for `F-Zero GX USA`). 3. Go to `Gecko Codes` tab and click `Download Codes`. 4. Check the boxes for the cheats you want to use then you can close Dolphin. 5. Navigate to `My Documents\Dolphin Emulator\GameSettings` by default for Windows (or `~/.local/share/dolphin-emu/GameSettings` for Linux). 6. Copy the .ini file with the ID of the game and paste it in your `RETROARCH_SAVES_FOLDER/dolphin-emu/User/GameSettings` folder. 7. Start the game, go to Quick Menu > Core Options and turn ON "Internal Cheats". 8. And finally Quick Menu > Close Content, restart the game and the cheats should now be active. If you need to enable another cheat later for that game, you don't need to do the whole process all over again. You can simply edit the .ini file(s) in your `RETROARCH_SAVES_FOLDER/dolphin-emu/User/GameSettings` folder structure with a text editor to add the cheat title under the line [Gecko_Enabled]. ## OpenGL Dolphin's OpenGL renderer can be used by setting RetroArch's video driver to gl. The common option for all operating systems is OpenGL, requiring hardware that supports OpenGL/Open GL ES 3.0 or higher. It is an older, pre-Vulkan API, slower than Vulkan but with better compatibility. If you encounter problems with other APIs, try this one. ## Vulkan Dolphin's Vulkan renderer can be used by setting RetroArch's video driver to vulkan. This is the latest and fastest API currently. It is most recommended for demanding less of your CPU, thus being the fastest. ## D3D11 Dolphin's Direct3D 11 renderer can be used by setting RetroArch's video driver to d3d11. In some cases Direct3D 11 may offer better performance than OpenGL, especially on integrated Intel graphics. ## Core options The Dolphin core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. - **Renderer** [dolphin_renderer] (**Hardware**|Software) - **Internal Resolution** [dolphin_efb_scale] (**x1 (640 x 528)**|x2 (1280 x 1056)|x3 (1920 x 1584)|x4 (2560 x 2112)|x5 (3200 x 2640)|x6 (3840 x 3168)) - **Widescreen (Wii)** [dolphin_widescreen] (**ON**|OFF) - **WideScreen Hack** [dolphin_widescreen_hack] (**OFF**|ON) - **Shader Compilation Mode** [dolphin_shader_compilation_mode] (**sync**|a-sync Skip Rendering|sync UberShaders|a-sync UberShaders) - **Wait for Shaders before Starting** [dolphin_wait_for_shaders] (**OFF**|ON) - **Progressive Scan** [dolphin_progressive_scan] (**ON**|OFF) - **PAL60** [dolphin_pal60] (**ON**|OFF) - **Max Anisotropy** [dolphin_max_anisotropy] (**1x**|2x|4x|8x|16x) - **Skip Presenting Duplicate Frames** [dolphin_skip_dupe_frames] (**ON**|OFF) - **Scaled EFB Copy** [dolphin_efb_scaled_copy] (**ON**|OFF) - **Force Texture Filtering** [dolphin_force_texture_filtering] (**OFF**|ON) - **Store EFB Copies on GPU** [dolphin_efb_to_texture] (**ON**|OFF) - **Texture Cache Accuracy** [dolphin_texture_cache_accuracy] (**Fast**|Middle|Safe) - **GPU Texture Decoding** [dolphin_gpu_texture_decoding] (**OFF**|ON) - **Fast Depth Calculation** [dolphin_fast_depth_calculation] (**ON**|OFF) - **Bounding Box Emulation** [dolphin_bbox_enabled] (**OFF**|ON) - **Disable EFB to VRAM** [dolphin_efb_to_vram] (**OFF**|ON) - **Load Custom Textures** [dolphin_load_custom_textures] (**OFF**|ON) - **CPU Core** [dolphin_cpu_core] (**JIT64/JITARM64**|Interpreter|Cached Interpreter) - **CPU Clock Rate** [dolphin_cpu_clock_rate] (**100%**|from 5% to 300%) - **Fastmem** [dolphin_fastmem] (**ON**|OFF) - **Wiimote IR Mode** [dolphin_ir_mode] (**Right Stick controls pointer (relative)**|Right Stick controls pointer (absolute)|Mouse controls pointer) - **Wiimote IR Vertical Offset** [dolphin_ir_offset] (**10**|from -50 to 50) - **Wiimote IR Total Yaw** [dolphin_ir_yaw] (**15**|from 0 to 100) - **Wiimote IR Total Pitch** [dolphin_ir_pitch] (**15**|from 0 to 100) - **Rumble** [dolphin_enable_rumble] (**ON**|OFF) - **Sensor Bar Position** [dolphin_sensor_bar_position] (**Bottom**|Top) - **Wiimote Continuous Scanning** [dolphin_wiimote_continuous_scanning] (**OFF**|ON) - **Use ports 5-8 for GameCube controllers in Wii mode** [dolphin_alt_gc_ports_on_wii] (**OFF**|ON) - **Audio Mixer Rate** [dolphin_mixer_rate] (**32000**|48000) - **DSP HLE** [dolphin_dsp_hle] (**ON**|OFF) - **DSP Enable JIT** [dolphin_dsp_jit] (**ON**|OFF) - **Language** [dolphin_language] (**English**|Japanese|German|French|Spanish|Italian|Dutch|Simplified Chinese|Traditional Chinese|Korean) - **Internal Cheats Enabled** [dolphin_cheats_enabled] (**OFF**|ON) - **OSD Enabled** [dolphin_osd_enabled] (**ON**|OFF) - **Log Level** [dolphin_log_level] (**Info**|Notice|Error|Warning) ## Joypad | RetroPad Inputs | GameCube Controller | Wiimote | Wiimote (sideways) | Wiimote + Nunchuk | Classic Controller | Classic Controller Pro | |------------------------------------------------ |---------------------|-------------|--------------------|-------------------|--------------------|------------------------| | ![](../image/retropad/retro_b.png) | B | B | 1 | B | B | B | | ![](../image/retropad/retro_y.png) | Y | 2 | B | Z | Y | Y | | ![](../image/retropad/retro_select.png) | | - | - | 2 | - | - | | ![](../image/retropad/retro_start.png) | Start | + | + | 1 | + | + | | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | D-Pad Up | D-Pad Up | D-Pad Up | D-Pad Up | D-Pad Up | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | D-Pad Down | D-Pad Down | D-Pad Down | D-Pad Down | D-Pad Down | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | D-Pad Left | D-Pad Left | D-Pad Left | D-Pad Left | D-Pad Left | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | D-Pad Right | D-Pad Right | D-Pad Right | D-Pad Right | D-Pad Right | | ![](../image/retropad/retro_a.png) | A | A | 2 | A | A | A | | ![](../image/retropad/retro_x.png) | X | 1 | A | C | X | X | | ![](../image/retropad/retro_l1.png) | | | | - | ZL | L | | ![](../image/retropad/retro_r1.png) | Z | | | + | ZR | R | | ![](../image/retropad/retro_l2.png) | L | | | Shake Nunchuk | L | ZL | | ![](../image/retropad/retro_r2.png) | R | Shake | Shake | Shake Wiimote | R | ZR | | ![](../image/retropad/retro_l3.png) | L-Analog | | | | | | | ![](../image/retropad/retro_r3.png) | R-Analog | Home | Home | Home | Home | Home | | ![](../image/retropad/retro_left_stick.png) X | Analog X | Tilt X | Tilt X | Nunchuk Stick X | Left Stick X | Left Stick X | | ![](../image/retropad/retro_left_stick.png) Y | Analog Y | Tilt Y | Tilt Y | Nunchuk Stick Y | Left Stick Y | Left Stick Y | | ![](../image/retropad/retro_right_stick.png) X | C-Stick X | | | Tilt X | Right Stick X | Right Stick X | | ![](../image/retropad/retro_right_stick.png) Y | C-Stick Y | | | Tilt Y | Right Stick Y | Right Stick Y | **NOTE:** The 'L-Analog' and 'R-Analog' inputs are half-presses of the analog L and R buttons, respectively. These inputs are required to progress in some games, such as Super Mario Sunshine. ## Compatibility [Compatibility Pages](https://dolphin-emu.org/compat/) ## External Links - [Official Dolphin Website](https://dolphin-emu.org/) - [Official Dolphin Github Repository](https://github.com/dolphin-emu/dolphin) - [Libretro Dolphin Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/dolphin_libretro.info) - [Report Libretro Dolphin Core Issues Here](https://github.com/libretro/dolphin/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0IcC4j9ggvxzZm2GiuufDMeU) ================================================ FILE: docs/library/dosbox.md ================================================ # DOS (DOSBox) ## Background DOSBox is a multiplatform DOS-emulator The DOSBox core has been authored by - DOSBox Team The DOSBox core is licensed under - [GPLv2](https://github.com/libretro/dosbox-libretro/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the DOSBox core have the following file extensions: - .exe - .com - .bat - .conf RetroArch database(s) that are associated with the DOSBox core: - [DOS](https://github.com/libretro/libretro-database/blob/master/rdb/DOS.rdb) ## Features Frontend-level settings or features that the DOSBox core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✕ | | Screenshots | ✔ | | Saves | - | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The DOSBox core's library name is 'DOSBox' ### Geometry and timing - The DOSBox core's core provided FPS is 60.0 - The DOSBox core's core provided sample rate is (Rate) - The DOSBox core's base width is 320 - The DOSBox core's base height is 200 - The DOSBox core's max width is 1024 - The DOSBox core's max height is 768 - The DOSBox core's core provided aspect ratio is 4/3 ## Loading content - To use you can either load an exe/com/bat file or a *.conf file. - If loading exe/com/bat the system directory will be searched for a 'dosbox.conf' file to load. If one isn't available default values will be used. This mode is equivalent to running a DOSBox binary with the specified file as the command line argument. - If loading a conf file DOSBox will be loaded with the options in the config file. This mode is useful if you just want to be dumped at a command prompt, but can also be used to load a game by putting commands in the autoexec section. - To be useful the frontend will need to have keyboard+mouse support, and all keyboard shortcuts need to be remapped. ## Usage DOSBox can load DOS executables or custom config files. To get started you can generate a config file by creating the DOSbox folder in your libretro SYSTEM directory, and then loading any DOS application, exit back to the command interpreter and then run config -wcd, Configuration files allow you far better control than core options so far. Eventually every single useable option will be exposed but in the meantime combining both is the best alternative. If you generate a default config it will always be loaded by default, but you can override it by saving your custom settings, preferably in the game folder. You can create a config like this: ``` [autoexec] @echo off mount d "/storage/roms/dos/game" d: game.exe ``` Then you can store this config in the game folder (or any other directory) and just the config instead of the exe file. Once you change a setting using the config command or via core options, you can always update the config file by using config -wc ## MIDI - To use MIDI you need MT32_CONTROL.ROM and MT32_PCM.ROM in the system directory of RetroArch.Then set: ``` [midi] mpu401=intelligent mididevice=mt32 ``` ## Core options The DOSBox core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Machine type** [dosbox_machine_type] (**vgaonly**|svga_s3|svga_et3000|svga_et4000|svga_paradise|hercules|cga|tandy|pcjr|ega) Select what machine will be emulated. - **Gamepad emulated mouse** [dosbox_emulated_mouse] (**enable**|disable) CPU cycles are divided in core options to allow fine control of the desired CPU cycles. Setting this too low may cause slow gameplay, setting this too high might cause sound crackling and bad performance. - **CPU cycles x 100000** [dosbox_cpu_cycles_0] (**0**|1|2|3|4|5|6|7|8|9) CPU cycles are divided in core options to allow fine control of the desired CPU cycles. Setting this too low may cause slow gameplay, setting this too high might cause sound crackling and bad performance. - **PU cycles x 10000** [dosbox_cpu_cycles_1] (**0**|1|2|3|4|5|6|7|8|9) CPU cycles are divided in core options to allow fine control of the desired CPU cycles. Setting this too low may cause slow gameplay, setting this too high might cause sound crackling and bad performance. - **CPU cycles x 1000** [dosbox_cpu_cycles_2] (**1**|2|3|4|5|6|7|8|9|0) CPU cycles are divided in core options to allow fine control of the desired CPU cycles. Setting this too low may cause slow gameplay, setting this too high might cause sound crackling and bad performance. - **CPU cycles x 100** [dosbox_cpu_cycles_3] (**0**|1|2|3|4|5|6|7|8|9") CPU cycles are divided in core options to allow fine control of the desired CPU cycles. Setting this too low may cause slow gameplay, setting this too high might cause sound crackling and bad performance. ## User 1 - 2 device types The DOSBox core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): - None - Input disabled. - **Gamepad** - Joypad - Joystick - Analog - Keyboard - Keyboard - Keyboard inputs are always active. Has keymapper support. ## Joypad | Input descriptors for Gamepad 2 Button | RetroPad Inputs | |----------------------------------------|---------------------------------------------| | Button 2 | ![](../image/retropad/retro_b.png) | | Button 1 | ![](../image/retropad/retro_y.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | Input descriptors for Gamepad 4 Button | RetroPad Inputs | |----------------------------------------|---------------------------------------------| | Button 3 | ![](../image/retropad/retro_b.png) | | Button 1 | ![](../image/retropad/retro_y.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | Button 4 | ![](../image/retropad/retro_a.png) | | Button 2 | ![](../image/retropad/retro_x.png) | | Input descriptors for Joystick 2 Button | RetroPad Inputs | |-----------------------------------------|------------------------------------------------| | Button 2 | ![](../image/retropad/retro_b.png) | | Button 1 | ![](../image/retropad/retro_y.png) | | Left Analog X | ![](../image/retropad/retro_left_stick.png) X | | Left Analog Y | ![](../image/retropad/retro_left_stick.png) Y | | Input descriptors for Joystick 4 Button | RetroPad Inputs | |-----------------------------------------|------------------------------------------------| | Button 3 | ![](../image/retropad/retro_b.png) | | Button 1 | ![](../image/retropad/retro_y.png) | | Button 4 | ![](../image/retropad/retro_a.png) | | Button 2 | ![](../image/retropad/retro_x.png) | | Left Analog X | ![](../image/retropad/retro_left_stick.png) X | | Left Analog Y | ![](../image/retropad/retro_left_stick.png) Y | | Right Analog X | ![](../image/retropad/retro_right_stick.png) X | | Right Analog Y | ![](../image/retropad/retro_right_stick.png) Y | | Input descriptors for Keyboard | RetroPad Inputs | |--------------------------------|---------------------------------------------| | Esc | ![](../image/retropad/retro_select.png) | | Enter | ![](../image/retropad/retro_start.png) | | Kbd Up | ![](../image/retropad/retro_dpad_up.png) | | Kbd Down | ![](../image/retropad/retro_dpad_down.png) | | Kbd Left | ![](../image/retropad/retro_dpad_left.png) | | Kbd Right | ![](../image/retropad/retro_dpad_right.png) | | Input descriptors for Emulated mouse | RetroPad Inputs | |--------------------------------------|------------------------------------------------| | Emulated Mouse Right Click | ![](../image/retropad/retro_l2.png) | | Emulated Mouse Left Click | ![](../image/retropad/retro_r2.png) | | Emulated Mouse X Axis | ![](../image/retropad/retro_right_stick.png) X | | Emulated Mouse Y Axis | ![](../image/retropad/retro_right_stick.png) Y | ## Keyboard | RetroKeyboard Inputs | Keyboard | |-------------------------------|--------------------| | Keyboard Backspace | Backspace | | Keyboard Tab | Tab | | Keyboard Return | Enter | | Keyboard Pause | Pause | | Keyboard Escape | Escape | | Keyboard Space | Space | | Keyboard ' | ' | | Keyboard , | , | | Keyboard . | . | | Keyboard / | / | | Keyboard 0 | 0 | | Keyboard 1 | 1 | | Keyboard 2 | 2 | | Keyboard 3 | 3 | | Keyboard 4 | 4 | | Keyboard 5 | 5 | | Keyboard 6 | 6 | | Keyboard 7 | 7 | | Keyboard 8 | 8 | | Keyboard 9 | 9 | | Keyboard ; | ; | | Keyboard - | - | | Keyboard = | = | | Keyboard [ | [ | | Keyboard \ | \ | | Keyboard ] | ] | | Keyboard ` | ` | | Keyboard a | a | | Keyboard b | b | | Keyboard c | c | | Keyboard d | d | | Keyboard e | e | | Keyboard f | f | | Keyboard g | g | | Keyboard h | h | | Keyboard i | i | | Keyboard j | j | | Keyboard k | k | | Keyboard l | l | | Keyboard m | m | | Keyboard n | n | | Keyboard o | o | | Keyboard p | p | | Keyboard q | q | | Keyboard r | r | | Keyboard s | s | | Keyboard t | t | | Keyboard u | u | | Keyboard v | v | | Keyboard w | w | | Keyboard x | x | | Keyboard y | y | | Keyboard z | z | | Keyboard Delete | Delete | | Keyboard Numpad 0 | Numpad 0 | | Keyboard Numpad 1 | Numpad 1 | | Keyboard Numpad 2 | Numpad 2 | | Keyboard Numpad 3 | Numpad 3 | | Keyboard Numpad 4 | Numpad 4 | | Keyboard Numpad 5 | Numpad 5 | | Keyboard Numpad 6 | Numpad 6 | | Keyboard Numpad 7 | Numpad 7 | | Keyboard Numpad 8 | Numpad 8 | | Keyboard Numpad 9 | Numpad 9 | | Keyboard Numpad . | Numpad . | | Keyboard Numpad / | Numpad / | | Keyboard Numpad * | Numpad * | | Keyboard Numpad - | Numpad - | | Keyboard Numpad + | Numpad + | | Keyboard Numpad Enter | Numpad Enter | | Keyboard Up | Up | | Keyboard Down | Down | | Keyboard Right | Left | | Keyboard Left | Right | | Keyboard Insert | Insert | | Keyboard Home | Home | | Keyboard End | End | | Keyboard Page Up | Page Up | | Keyboard Page Down | Page Down | | Keyboard F1 | F1 | | Keyboard F2 | F2 | | Keyboard F3 | F3 | | Keyboard F4 | F4 | | Keyboard F5 | F5 | | Keyboard F6 | F6 | | Keyboard F7 | F7 | | Keyboard F8 | F8 | | Keyboard F9 | F9 | | Keyboard F10 | F10 | | Keyboard F11 | F11 | | Keyboard F12 | F12 | | Keyboard Num Lock | Num Lock | | Keyboard Caps Lock | Caps Lock | | Keyboard Scroll Lock | Scroll Lock | | Keyboard Right Shift | Right Shift | | Keyboard Left Shift | Left Shift | | Keyboard Right Control | Right Control | | Keyboard Left Control | Left Control | | Keyboard Right Alt | Right Alt | | Keyboard Left Alt | Left Alt | | Keyboard Sys Req | Print Screen | ## External Links - [Official DOSBox Website](https://www.dosbox.com/) - [Official/Original DOSBox SourceForge Repository](https://sourceforge.net/projects/dosbox/) - [Libretro DOSBox Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/dosbox_libretro.info) - [Libretro DOSBox Github Repository](https://github.com/libretro/dosbox-libretro) - [Report Libretro DOSBox Core Issues Here](https://github.com/libretro/dosbox-libretro/issues) ================================================ FILE: docs/library/dosbox_pure.md ================================================ # DOS (DOSBox Pure) ## Background DOSBox Pure is a fork of the multiplatform MS-DOS emulator, DOSBox. It was built by Psyraven in 2020 specifically for RetroArch/Libretro and implements advanced features like save states, an on-screen keyboard, highly customizable controller setup or rewinding. DOSBox Pure aims for simplicity and ease of use. The DOSBox Pure core has been authored by - DOSBox Team - Psyraven The DOSBox Pure core is licensed under - [GPLv2](https://github.com/libretro/dosbox-libretro/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the DOSBox Pure core has the following file extensions: - .zip _(see [Load games from ZIP](#load-games-from-zip))_ - .dosz _(alternative extension to .ZIP)_ - .exe _(DOS program)_ - .com _(DOS program)_ - .bat _(DOS batch file)_ - .iso _(CDROM image)_ - .cue _(CDROM image)_ - .ins _(CDROM image)_ - .img _(hard disk/floppy disk/CDROM image)_ - .ima _(hard disk/floppy disk image)_ - .vhd _(hard disk image)_ - .jrc _(PCjr cartridge)_ - .tc _(PCjr cartridge)_ - .m3u _(playlist for multiple CDROM/floppy) - .m3u8 _(playlist for multiple CDROM/floppy) - .conf _(bootable, see [Loading of dosbox.conf files](#loading-of-dosboxconf-files))_ RetroArch database(s) that are associated with the DOSBox Pure core: - [DOS](https://github.com/libretro/libretro-database/blob/master/rdb/DOS.rdb) ## Features Frontend-level settings or features that the DOSBox Pure core respects. | Feature | Supported | |-------------------------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | [Rewind](#rewind-support) | ✔ | | Netplay | ✕ | | [Core Options](#core-options) | ✔ | | RetroAchievements | ✕ | | [RetroArch Cheats](#cheats-support) | ✔ | | [Native Cheats](#cheats-support) | ✔ | | [Controls](#controls) | ✔ | | [Remapping](#gamepad-mapper) | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | Softpatching | ✕ | | Disk Control | ✔ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### MIDI playback with SoundFonts If DOSBox Pure finds one or more `.SF2` sound font files in the `system` directory of the frontend, one of them can be selected via the `Audio > MIDI Output` [core option](#audio-options). This sound font will then be used to play `General Midi` and `Sound Canvas` music. ### MPU-401 MIDI device emulation through MUNT To emulate pre-General MIDI (MPU-401) devices such as the Roland MT-32, CM-32L, CM-64 and LAPC-I, you need the correct ROM files, e.g., MT32_CONTROL.ROM and MT32_PCM.ROM (more details about necessary files [here](https://github.com/munt/munt/blob/master/mt32emu/src/ROMInfo.cpp#L28)). Place them in the RetroArch `system` directory. Then, bring up DOSBox Pure's options and in `Audio > MIDI Output`, select the device you want to emulate (e.g., `Roland MT-32`). ### Cheats support DOSBox Pure exposes its memory for cheats in the libretro frontend. For details how to use it and how to find new cheats while playing the game, check the [Libretro documentation for cheats](https://docs.libretro.com/guides/cheat-codes/). This can also be used to add controller rumble support to DOS games. ### Save states The DOSBox Pure core fully supports libretro save states. Make sure to test it in each game before using it. Complex late era DOS games might have problems. Be aware that states saved with different video or cpu settings are not loadable. Read more about [save file handling](#save-file-handling). ### Rewind support Using the [core option](#emulation-options) `Save States Support`, rewinding can be enabled. Keep in mind that rewind support comes at a high performance cost. ## Geometry and timing - The DOSBox Pure core's core provided FPS is dependent on the DOS application - The DOSBox Pure core's core provided sample rate is dependent on the 'Audio > Audio Sample Rate' [core option](#audio-options) - The DOSBox Pure core's base width is 320 - The DOSBox Pure core's base height is 200 - The DOSBox Pure core's max width is 1280 - The DOSBox Pure core's max height is 1024 - The DOSBox Pure core's core provided aspect ratio is dependent on the DOS application and the 'Video > Aspect Ratio Correction' [core option](#video-options) ## Loading content ### Load games from ZIP DOSBox Pure can load games directly from ZIP files without the need to extract them. ### Store modifications in separate save files Changes made to a loaded ZIP file will be stored as a separate ZIP file into the [libretro saves directory](https://docs.libretro.com/guides/change-directories/#savefile-and-savestate). If a game is loaded directly without using a ZIP file, the saves directory is not used. ### Mount disc images from inside ZIP files CD images (ISO or CUE) and floppy disk images (IMG/IMA/VHD) can be mounted directly from inside ZIP files. The system will automatically mount the first found disk image as the A: or D: drive. Additional disks can be loaded or swapped by using the `Disc Control` menu in RetroArch. When mounting a ZIP file which has just a single directory in its root, core versions before 0.9.0 used to mount that directory as the C: drive. Since 0.9.0, the core will mount the root of the ZIP to improve compatibility with DOS games that need to be installed in a specific location on the hard drive. The old behavior will still be used if an old save file (named `GAME.save.zip`) exists. The new behavior uses a differently named save file (`GAME.pure.zip`). The start menu also offers the option to mount or unmount an image. ### Start menu with auto start ![The DOSBox Pure Start Menu](https://raw.githubusercontent.com/libretro/dosbox-pure/main/images/startmenu.png) This is the first screen that appears when loading a game. It offers a gamepad controllable list of all executable files for the loaded game. By pressing right an item can be selected as the default which will skip the menu on the next launch. By pressing right multiple times, a number of frames can be specified that will automatically be skipped on start. This can be used to skip over loading screens or start-up sequences. If there is only a single executable, the menu will not show and directly run the file. To force the menu to be shown, hold shift on the keyboard or L2 or R2 on the gamepad while selecting `Restart` in the core menu. ### Installing CD-ROM games from disc images (ISO etc.) and running them This can be done in 3 steps: 1. In order to install a game from a CD-ROM image (e.g., a .iso file), use the "Load Content" option in the RetroArch main menu. Navigate to the ISO and launch it with the DOSBox Pure core. 2. From the start menu, select the executable on the CD-ROM to install the game (probably something like `SETUP.EXE`, `INSTALL.EXE`, `START.EXE`...). Follow the installer's instructions to install the game in any local directory of your choice (e.g., `C:\`, `C:\C&C\`, ...). 3. Now, the next time you run the ISO in DOSBox Pure (same way as in step 1 above), the start menu will feature the "local" executables, e.g.: `C:\C&C\C&C.EXE`. They'll be available to select above the executables from mounted discs. Launch the correct executable to run the game. See screenshot in "[Start menu with auto start](#start-menu-with-auto-start)" section above for reference. ### Directly run PC booter games from the start menu ![Directly run PC booter games from the start menu](https://user-images.githubusercontent.com/14200249/164041304-f921c806-8790-4bee-b9fa-5826714012e3.gif) When loading a ZIP file which contains a floppy or hard-disk image or loading such a disk image directly, the start menu will show an additional option `[BOOT IMAGE FILE]`. When selected, a list of system modes (emulated graphics card) will be shown and once a mode is selected, DOSBox Pure will try to boot from the mounted image. While running a booter game, the mounted disk can be easily swapped with the Disc Control menu or hotkeys set in the frontend. There's also support for swapping floppy disk images (or PCjr cartridges) at runtime via a frontend's Disc Control menu and hotkeys. ### Auto-execution of DOSBOX.BAT The core automatically executes `DOSBOX.BAT` instead of showing the start menu if it exists in the mounted ZIP or path. ### Loading of dosbox.conf files If a .conf file gets selected in the frontend, DOSBox Pure will load it directly and run its autoexec commands. Alternatively, a .conf file can get loaded automatically depending on the 'Emulation > Loading of dosbox.conf' [core option](#emulation-options). There are two modes that can be enabled: - "Try 'dosbox.conf' in the loaded content (ZIP or folder)" - Will load C:\DOSBOX.CONF automatically if it exists in the mounted ZIP or path - "Try '.conf' with same name as loaded content (next to ZIP or folder)" - Will automatically load GAME.conf next to GAME.zip if it exists. ### Loading M3U8 files If the core gets loaded with a `.m3u8` file, all files listed in it will be added to the disc swap menu. The first image will automatically get mounted as the A: or D: drive depending on whether it is a CD or floppy disk image. ## Tips, Q&A, Troubleshooting ### Smooth scrolling You might have trouble getting stutter-free scrolling in some games (cf. [this bug report](https://github.com/schellingb/dosbox-pure/issues/128)). There are a number of things you can try to remedy this: - In `Quick Menu > Options > Emulation Options`, set `Force 60 FPS Output` to ON. - In RetroArch's settings, navigate to `Video` and set `Threaded Video` to OFF. - Try `Video` > `Output` > `Set Display-Reported Refresh Rate`. - Try setting `Video` > `Synchronization` > `Vertical Sync` to ON. - If using a variable refresh rate screen (G-Sync, FreeSync, HDMI 2.1 VRR): navigate to `Video` > `Synchronization` and set `Sync to Exact Content Framerate (G-Sync, FreeSync)` to ON. ### Playing with keyboard and mouse To play not with a gamepad but with keyboard and mouse, be sure to use the '[Game Focus](https://docs.libretro.com/guides/input-and-controls/#cores-with-direct-keyboard-input)' mode available in RetroArch. By default, you can toggle game focus by pressing the scroll lock key. While game focus is active, the RetroArch hotkeys are disabled and keyboard presses will not cause [RetroPad](https://docs.libretro.com/guides/input-and-controls/) button presses (which could cause multiple keys to be pressed at once). You can change the hotkey for game focus mode in RetroArch's ["Hotkeys" menu](https://docs.libretro.com/guides/input-and-controls/#hotkeys). ### ZIP files can be renamed to DOSZ If your libretro frontend wants to load the content of `.ZIP` files instead of sending it to DOSBox Pure to load, the files can be renamed from `.ZIP` to `.DOSZ`. This is especially useful for CD images in ZIP format which RetroArch refuses to append through its `Disc Control` menu. Using an [.M3U8 file](#loading-m3u8-files) also avoids this problem. ### Force opening the start menu If you have assigned an auto start item in the start menu but want to go back to it, hold shift on the keyboard or L2 or R2 on the gamepad while selecting `Restart` in the core menu. ### Mount ZIP as A or D drive If you have a ZIP file you want to load as a fake floppy disk or fake CD-ROM, there are multiple options. - The easiest is to rename the file from `.ZIP` to e.g., `.D.ZIP` (to use the D: drive). - You can also edit the RetroArch `.LPL` playlist file to add a `#D` after the file like `game.zip#D`. - A third option is available inside DOSBox Pure with a new remount command that can be called with REMOUNT C: D: to remount the C: drive to D:. This can for example be used in a startup batch file. ### Change disk label with label command DOSBox Pure by default uses the first word of the ZIP file name as the label of the mounted disk. Some games require a specific label on a floppy or a CD-ROM so DOSBox Pure offers a new command to change the label of a mounted disk. For example, `LABEL C: HELLO` changes the label of the C: drive. This label is not saved anywhere and needs to be reapplied on every launch so it's best to add the command in a startup batch file. You can run the `MOUNT` command to check all mounted disks and their disk label. ### Keyboard layout defaults to US The keyboard layout defaults to the US Layout (QWERTY). If you need a different layout, you can change the core option `Input Options > Advanced > Keyboard Layout`. ### Save file handling When modifications to the file system loaded from a ZIP file happen, these modifications are written into a separate save file. You can find these save files inside the data directory of your libretro frontend, usually in a sub-directory called `saves`, or any other directory you have set in `RetroArch's Settings > Directory > Savefile`. - Save files get re-written to disk a short while after a modification happens in the file system. - The larger the save, the less often it will be written out. - Up to 1MB of total save data, it will be written out 2 seconds after the previous file modification. Then gradually until at max 59MB and more, it will be written out 60 seconds after the last file modification. ## Core options The DOSBox Pure core has the following options that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) mean that core has to be closed for the new setting to be applied on next launch. ### Manage Core Options Save or remove option overrides for the current content. - **Save game options** Saves current options specifically for running game. - **Save Content Directory Options** Saves current options specifically for running game's content directory. - **Reset Options** Reset all core options to default values. ### Emulation Options Core specific settings (latency, save states, start menu). - **Force 60 FPS Output** [dosbox_pure_force60fps] (**OFF** | ON) Enable this to force output at 60FPS. Use this if you encounter screen tearing or vsync issues. - **Show Performance Statistics** [dosbox_pure_perfstats] (**Disabled** | Simple | Detailed information) Enable this to show statistics about performance and framerate and check if emulation runs at full speed. - **Save States Support** [dosbox_pure_savestate] (**Enable save states** | Enable save states with rewind | OFF) Make sure to test it in each game before using it. Complex late era DOS games might have problems. Be aware that states saved with different video, CPU or memory settings are not loadable. Rewind support comes at a high performance cost and needs at least 40MB of rewind buffer. - **Loading of dosbox.conf** [dosbox_pure_conf] (**Disabled conf support (default)** | Try 'dosbox.conf' in the loaded content (ZIP or folder) | Try '.conf' with same name as loaded content (next to ZIP or folder)) DOSBox Pure is meant to be configured via core options but optionally supports loading of legacy .conf files. - **Start Menu** [dosbox_pure_menu_time] (**Show at start, shut down core 5 seconds after auto started game exit** | Show at start, shut down core 3 seconds after auto started game exit | Show at start, shut down core immediately after auto started game exit | Show at start, show again after game exit (default) | Always show menu on startup and after game exit, ignore auto start setting) Set the behavior of the start menu before and after launching a game. You can also force it to open by holding shift or L2/R2 when selecting 'Restart'. - **Advanced > Input Latency** [dosbox_pure_latency] (**Default** | Lowest latency - See CPU usage setting below! | Irregular latency - Might improve performance on low-end devices) By default the core operates in a high performance mode with good input latency. There is a special mode available which minimizes input latency further requiring manual tweaking. - **Advanced > Low latency CPU usage** [dosbox_pure_auto_target] (**90%** | 50% > 100%) In low latency mode when emulating DOS as fast as possible, how much time per frame should be used by the emulation. If the video is stuttering, lower this or improve render performance in the frontend (for example by disabling vsync or video processing). Use the performance statistics to easily find the maximum that still hits the emulated target framerate. ### Input Options Keyboard, mouse and joystick settings. - **Bind Unused Buttons** [dosbox_pure_bind_unused] (**On** | Off) Bind all unused controller buttons to keyboard keys. Can be remapped in the Controls section of the core settings. - **Enable On Screen Keyboard** [dosbox_pure_on_screen_keyboard] (**On** | Off) Enable the On Screen Keyboard feature which can be activated with the L3 button on the controller. - **Bind Mouse Wheel To Key** [dosbox_pure_mouse_wheel] (**Left-Bracket/Right-Bracket** | Comma/Period | Page-Up/Page-Down | Home/End | Delete/Page-Down | Minus/Equals | Semicolon/Quote | Numpad Minus/Plus | Numpad Divide/Multiply | Up/Down | Left/Right | Q/E | Disable) Bind mouse wheel up and down to two keyboard keys to be able to use it in DOS games. - **Mouse Sensitivity** [dosbox_pure_mouse_speed_factor] (**100%** | 20% to 100% in 5% increments | 100% to 500% in 10% increments) Sets the overall mouse cursor movement speed. - **Advanced > Horizontal Mouse Sensitivity** [dosbox_pure_mouse_speed_factor_x] (**100%** | 20% to 100% in 5% increments | 100% to 500% in 10% increments) Experiment with this value if the mouse is too fast/slow when moving left/right. - **Advanced > Use Mouse Input** [dosbox_pure_mouse_input] (**ON** | OFF) You can disable input handling from a mouse or a touchscreen (emulated mouse through joypad will still work). - **Advanced > Automatic Game Pad Mappings** [dosbox_pure_auto_mapping] (**On (default)** | Enable with notification on game detection | Off) DOSBox Pure can automatically apply a gamepad control mapping scheme when it detects a game. These button mappings are provided by the Keyb2Joypad Project (by Jemy Murphy and bigjim). - **Advanced > Keyboard Layout** [dosbox_pure_keyboard_layout] (**US (default)** | UK | Belgium | Brazil | Croatia | Czech Republic | Denmark | Finland | France | Germany | Greece | Hungary | Iceland | Italy | Netherlands | Norway | Poland | Portugal | Russia | Slovakia | Slovenia | Spain | Sweden | Switzerland (German) | Switzerland (French) | Turkey) Select the keyboard layout (will not change the On Screen Keyboard). - **Advanced > Menu Transparency** [dosbox_pure_menu_transparency] (**15%** | 10% to 100% in 10% increments) Set the transparency level of the On Screen Keyboard and the Gamepad Mapper. - **Advanced > Joystick Analog Deadzone** [dosbox_pure_joystick_analog_deadzone] (**15%** | 0% to 35% in 5% increments) Set the deadzone of the joystick analog sticks. May be used to eliminate drift caused by poorly calibrated joystick hardware. - **Advanced > Enable Joystick Timed Intervals** [dosbox_pure_joystick_timed] (**On (default)** | Off) Enable timed intervals for joystick axes. Experiment with this option if your joystick drifts. ### Performance Options Adjust the performance of the emulated CPU. - **Emulated Performance** [dosbox_pure_cycles] (**AUTO - DOSBox will try to detect performance needs (default)** | MAX - Emulate as many instructions as possible | 8086/8088, 4.77 MHz from 1980 (315 cps) | 286, 6 MHz from 1982 (1320 cps) | 286, 12.5 MHz from 1985 (2750 cps) | 386, 20 MHz from 1987 (4720 cps) | 386DX, 33 MHz from 1989 (7800 cps) | 486DX, 33 MHz from 1990 (13400 cps) | 486DX2, 66 MHz from 1992 (26800 cps) | Pentium, 100 MHz from 1995 (77000 cps) | Pentium II, 300 MHz from 1997 (200000 cps) | Pentium III, 600 MHz from 1999 (500000 cps) | AMD Athlon, 1.2 GHz from 2000 (1000000 cps)) The raw performance that DOSBox will try to emulate. - **Detailed > Performance Scale** [dosbox_pure_cycles_scale] (**100%** | 20% to 200% in 5% increments) Fine tune the emulated performance for specific needs. - **Detailed > Limit CPU Usage** [dosbox_pure_cycle_limit] (**100%** | 20% to 100% in 1% increments) When emulating DOS as fast as possible, how much time per frame should be used by the emulation. Lower this if your device becomes hot while using this core. ### Video Options Settings for the emulated graphics card and aspect ratio. - **Emulated Graphics Chip (restart required)** [dosbox_pure_machine] (**SVGA (Super Video Graphics Array) (default)** | VGA (Video Graphics Array) | EGA (Enhanced Graphics Adapter | CGA (Color Graphics Adapter) | Tandy (Tandy Graphics Adapter | Hercules (Hercules Graphics Card) | PCjr) The type of graphics chip that DOSBox will emulate. - **CGA Mode** [dosbox_pure_cga] (**Early model, composite mode auto (default)** | Early model, composite mode on | Early model, composite mode off | Late model, composite mode auto | Late model, composite mode on | Late model, composite mode off) The CGA variation that is being emulated. - **Hercules Color Mode** [dosbox_pure_hercules] (**Black & white (default)** | Black & amber | Black & green) The color scheme for Hercules emulation. - **SVGA Mode (restart required)** [dosbox_pure_svga] (**S3 Trio64 (default)** | S3 Trio64 no-line buffer hack (reduces flickering in some games) | S3 Trio64 VESA 1.3 | Tseng Labs ET3000 | Tseng Labs ET4000 | Paradise PVGA1A) The SVGA variation that is being emulated. Try changing this if you encounter graphical glitches. - **Aspect Ratio Correction** [dosbox_pure_aspect_correction] (**Off (default)** | On) When enabled, the core's aspect ratio is set to what a CRT monitor would display. ### System Options Other system settings for emulated RAM and CPU. - **Memory Size (restart required)** [dosbox_pure_memory_size] (**16 MB (default)** | Disable extended memory (no EMS/XMS) | 4 MB | 8 MB | 24 MB | 32 MB (unsafe) | 48 MB (unsafe) | 64 MB (unsafe) | 96 MB (unsafe) | 128 MB (unsafe) | 224 MB (unsafe)) The amount of (high) memory that the emulated machine has. You can also disable extended memory (EMS/XMS). Using more than the default is not recommended, due to incompatibility with certain games and applications. - **CPU Type (restart required)** [dosbox_pure_cpu_type] (**Auto - Mixed feature set with maximum performance and compatibility** | 386 - 386 instruction with fast memory access | 386 (slow) - 386 instruction set with memory privilege checks | 386 (prefetch) - With prefetch queue emulation (only on 'auto' and 'normal' core) | 486 (slow) - 486 instruction set with memory privilege checks | Pentium (slow) - 586 instruction set with memory privilege checks) Emulated CPU type. Auto is the fastest choice. Games that require specific CPU type selection: 386 (prefetch): X-Men: Madness in The Murderworld, Terminator 1, Contra, Fifa International Soccer 1994 486 (slow): Betrayal in Antara Pentium (slow): Fifa International Soccer 1994, Windows 95/Windows 3.x games - **Advanced > CPU Core** [dosbox_pure_cpu_core] (**Auto - Real-mode games use normal, protected-mode games use dynamic** | Dynamic - Dynamic recompilation (fast, using dynamic_x86 implementation) | Auto - Real-mode games use normal, protected-mode games use dynamic | Dynamic - Dynamic recompilation (fast, using dynrec implementation) | **Normal (interpreter)** | Simple (interpreter optimized for old real-mode games)) Emulation method (DOSBox CPU core) used. ### Audio Options MIDI, SoundBlaster and other audio settings. - **Audio Sample Rate (restart required)** [dosbox_pure_audiorate] (48000 | 44100 | 32730 | 32000 | 22050 | 16000 | 11025 | 8000 | 49716) This should match the frontend audio output rate (Hz) setting. 49716 is for perfect OPL emulation. - **SoundBlaster Settings** [dosbox_pure_sblaster_conf] (**Port 0x220, IRQ 7, 8-Bit DMA 1, 16-bit DMA 5** | Port 0x220, IRQ 5, 8-Bit DMA 1, 16-bit DMA 5 | Port 0x240, IRQ 7, 8-Bit DMA 1, 16-bit DMA 5 | Port 0x240, IRQ 7, 8-Bit DMA 3, 16-bit DMA 7 | Port 0x240, IRQ 2, 8-Bit DMA 3, 16-bit DMA 7 | Port 0x240, IRQ 5, 8-Bit DMA 3, 16-bit DMA 5 | Port 0x240, IRQ 5, 8-Bit DMA 1, 16-bit DMA 5 | Port 0x240, IRQ 10, 8-Bit DMA 3, 16-bit DMA 7 | Port 0x280, IRQ 10, 8-Bit DMA 0, 16-bit DMA 6 | Port 0x210, IRQ 5, 8-Bit DMA 1, 16-bit DMA 5) Set the address, interrupt, low 8-bit and high 16-bit DMA. - **MIDI Output** [dosbox_pure_midi] (will cycle through the .ROMs or .SF2s you have installed, + frontend MIDI driver) Select the .SF2 SoundFont file, .ROM file or interface used for MIDI output. To add SoundFonts or ROM files, copy them into the 'system' directory of the frontend. To use the frontend MIDI driver, make sure it's set up correctly. - **Advanced > SoundBlaster Type** [dosbox_pure_sblaster_type] (**SoundBlaster 16 (default)** | SoundBlaster Pro 2 | SoundBlaster Pro | SoundBlaster 2.0 | SoundBlaster 1.0 | GameBlaster | none) Type of emulated SoundBlaster card. - **Advanced > SoundBlaster Adlib/FM Mode** [dosbox_pure_sblaster_adlib_mode] (**Auto (select based on the SoundBlaster type) (default)** | CMS (Creative Music System / GameBlaster) | OPL-2 (AdLib / OPL-2 / Yamaha 3812) | Dual OPL-2 (Dual OPL-2 used by SoundBlaster Pro 1.0 for stereo sound) | OPL-3 (AdLib / OPL-3 / Yamaha YMF262) | OPL-3 Gold (AdLib Gold / OPL-3 / Yamaha YMF262)) The SoundBlaster emulated FM synth mode. All modes are Adlib compatible except CMS. - **Advanced > SoundBlaster Adlib Provider** [dosbox_pure_sblaster_adlib_emu] (**Default** | High quality Nuked OPL3) Provider for the Adlib emulation. Default has good quality and low performance requirements. - **Advanced > Enable Gravis Ultrasound (restart required)** [dosbox_pure_gus] (**Off (default)** | On) Enable Gravis Ultrasound emulation. Settings are fixed at port 0x240, IRQ 5, DMA 3. If the ULTRADIR variable needs to be different than the default 'C:\\ULTRASND' you need to issue 'SET ULTRADIR=...' in the command line or in a batch file. ## Controls ### Automated controller mappings When a game is loaded, DOSBox Pure will try to detect the game and apply a controller mapping. To see the applied mapping, check the `Port 1 Controls` screen in the RetroArch menu. It will show `Detected Automatic Key Mapping: `. Additionally you can set the core option `Input > Advanced > Automatic Game Pad Mappings` to `Enable with notification on game detection`. ### Mouse emulation On the `Controls` screen in the RetroArch menu, there are 2 mouse emulation modes available by switching the `Device Type` setting of any port with left/right. There is `Mouse with Left Analog Stick` and `Mouse with Right Analog Stick`. - When choosing left stick, the face buttons (B/A) will be used as left/right mouse buttons. - For the right stick, the shoulder buttons L/R will be used as left/right mouse buttons. - The X button is the middle mouse button and L2/R2 can be used to speed up or slow down mouse movement. There is also the core option `Input > Mouse Sensitivity` to increase/decrease mouse movement speed. ### Keyboard emulation For games that don't have automated controller mappings or are not detected successfully, by default the option `Input > Bind Unused Buttons` will assign all unused buttons on the game pad with a respective default key. If the `Device Type` on the `Controls` screen in the RetroArch menu of any port is set to `Generic Keyboard Bindings`, all buttons will be assigned with a keyboard key. Additionally, it can be set to `Custom Keyboard Bindings` which will allow fully customizable mappings. ### Joystick emulation There are multiple DOS era joysticks available as mappings on the `Controls` screen in the RetroArch menu. `Gravis GamePad (1 D-Pad, 4 Buttons)`, `Basic joystick (2 Axes, 2 Buttons)`, `ThrustMaster Flight Stick (3 axes, 4 buttons, 1 hat)` and `Control both DOS joysticks (4 axes, 4 buttons)`. These can be assigned to any port and the button layout can be remapped as with any other device type. ### On-screen keyboard ![DOSBox Pure On-Screen Keyboard](https://raw.githubusercontent.com/libretro/dosbox-pure/main/images/onscreenkeyboard.png) By pressing L3 on the gamepad (usually by pushing in the left analog stick), the on-screen keyboard will open. The cursor can be controlled with the controller (or mouse or keyboard) and L2/R2 will speed up or slow down the move speed. By clicking a key on the on-screen keyboard for 0.5 seconds, it will be held down, clicking it again will release it. This allows multiple keys to be pressed at the same time through the on-screen-keyboard. !!!tip Depending on your controller, you might experience a slight drift (the cursor moving on its own). Fix this by going to `Settings > Input` in RetroArch and nudging the option `Analog Deadzone` up a bit (e.g., 0.3). If the cursor is moved above the middle of the screen, the keyboard will move to the top. The button can be remapped in the controls menu and there is also a core option to disable it entirely. ### Gamepad Mapper ![The DOSBox Pure gamepad mapper](https://raw.githubusercontent.com/libretro/dosbox-pure/main/images/padmapper.png) If you need even more customization of the controls than provided by the [Automated controller mappings](#automated-controller-mappings), or the various presets for [mouse](#mouse-emulation), [keyboard](#keyboard-emulation) and [joysticks](#joystick-emulation), you can use the gamepad mapper introduced in version 0.9.0 in April, 2022. To open it, click the "PAD MAPPER" button in the On-screen keyboard (cf. above). It is available any time in-game and changes are immediately saved and applied when closing the mapper. Up to 4 functions can be mapped for any button/direction of the gamepad. A mapping can be to any function of the 3 emulated input devices: keyboard, mouse or joystick. ## Joypad (RetroPad) | Input descriptors for Gamepad 2 Button | RetroPad Inputs | |----------------------------------------|---------------------------------------------| | Button 2 | ![](../image/retropad/retro_b.png) | | Button 1 | ![](../image/retropad/retro_y.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | Input descriptors for Gamepad 4 Button | RetroPad Inputs | |----------------------------------------|---------------------------------------------| | Button 3 | ![](../image/retropad/retro_b.png) | | Button 1 | ![](../image/retropad/retro_y.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | Button 4 | ![](../image/retropad/retro_a.png) | | Button 2 | ![](../image/retropad/retro_x.png) | | Input descriptors for Joystick 2 Button | RetroPad Inputs | |-----------------------------------------|------------------------------------------------| | Button 2 | ![](../image/retropad/retro_b.png) | | Button 1 | ![](../image/retropad/retro_y.png) | | Left Analog X | ![](../image/retropad/retro_left_stick.png) X | | Left Analog Y | ![](../image/retropad/retro_left_stick.png) Y | | Input descriptors for Joystick 4 Button | RetroPad Inputs | |-----------------------------------------|------------------------------------------------| | Button 3 | ![](../image/retropad/retro_b.png) | | Button 1 | ![](../image/retropad/retro_y.png) | | Button 4 | ![](../image/retropad/retro_a.png) | | Button 2 | ![](../image/retropad/retro_x.png) | | Left Analog X | ![](../image/retropad/retro_left_stick.png) X | | Left Analog Y | ![](../image/retropad/retro_left_stick.png) Y | | Right Analog X | ![](../image/retropad/retro_right_stick.png) X | | Right Analog Y | ![](../image/retropad/retro_right_stick.png) Y | | Input descriptors for Keyboard - Port 1 | RetroPad Inputs | |-----------------------------------------|------------------------------------------------| | Kbd Up | ![](../image/retropad/retro_dpad_up.png) | | Kbd Down | ![](../image/retropad/retro_dpad_down.png) | | Kbd Left | ![](../image/retropad/retro_dpad_left.png) | | Kbd Right | ![](../image/retropad/retro_dpad_right.png) | | Esc | ![](../image/retropad/retro_select.png) | | Enter | ![](../image/retropad/retro_start.png) | | Space | ![](../image/retropad/retro_x.png) | | Left Shift | ![](../image/retropad/retro_y.png) | | Left Ctrl | ![](../image/retropad/retro_b.png) | | Left Alt | ![](../image/retropad/retro_a.png) | | 1 | ![](../image/retropad/retro_l1.png) | | 2 | ![](../image/retropad/retro_r1.png) | | 3 | ![](../image/retropad/retro_l2.png) | | 4 | ![](../image/retropad/retro_r2.png) | | F1 | ![](../image/retropad/retro_l3.png) | | F2 | ![](../image/retropad/retro_r3.png) | | Kbd Left/Right | ![](../image/retropad/retro_left_stick.png) X | | Kbd Up/Down | ![](../image/retropad/retro_left_stick.png) Y | | Home/End | ![](../image/retropad/retro_right_stick.png) X | | PgUp/PgDn | ![](../image/retropad/retro_right_stick.png) Y | | Input descriptors for Keyboard - Port 2 | RetroPad Inputs | |-----------------------------------------|------------------------------------------------| | 8 | ![](../image/retropad/retro_dpad_up.png) | | 2 | ![](../image/retropad/retro_dpad_down.png) | | 4 | ![](../image/retropad/retro_dpad_left.png) | | 6 | ![](../image/retropad/retro_dpad_right.png) | | Period | ![](../image/retropad/retro_select.png) | | Enter | ![](../image/retropad/retro_start.png) | | 5 | ![](../image/retropad/retro_x.png) | | 1 | ![](../image/retropad/retro_y.png) | | 0 | ![](../image/retropad/retro_b.png) | | 3 | ![](../image/retropad/retro_a.png) | | 7 | ![](../image/retropad/retro_l1.png) | | 9 | ![](../image/retropad/retro_r1.png) | | Minus | ![](../image/retropad/retro_l2.png) | | Plus | ![](../image/retropad/retro_r2.png) | | Divide | ![](../image/retropad/retro_l3.png) | | Multiply | ![](../image/retropad/retro_r3.png) | | 4/6 | ![](../image/retropad/retro_left_stick.png) X | | 8/2 | ![](../image/retropad/retro_left_stick.png) Y | | Minus/Plus | ![](../image/retropad/retro_right_stick.png) X | | Divide/Multiply | ![](../image/retropad/retro_right_stick.png) Y | | Input descriptors for Keyboard - Port 3 | RetroPad Inputs | |-----------------------------------------|------------------------------------------------| | Q | ![](../image/retropad/retro_dpad_up.png) | | A | ![](../image/retropad/retro_dpad_down.png) | | Z | ![](../image/retropad/retro_dpad_left.png) | | X | ![](../image/retropad/retro_dpad_right.png) | | G | ![](../image/retropad/retro_select.png) | | H | ![](../image/retropad/retro_start.png) | | D | ![](../image/retropad/retro_x.png) | | F | ![](../image/retropad/retro_y.png) | | C | ![](../image/retropad/retro_b.png) | | S | ![](../image/retropad/retro_a.png) | | W | ![](../image/retropad/retro_l1.png) | | E | ![](../image/retropad/retro_r1.png) | | R | ![](../image/retropad/retro_l2.png) | | T | ![](../image/retropad/retro_r2.png) | | V | ![](../image/retropad/retro_l3.png) | | B | ![](../image/retropad/retro_r3.png) | | Z/X | ![](../image/retropad/retro_left_stick.png) X | | Q/A | ![](../image/retropad/retro_left_stick.png) Y | | J/L | ![](../image/retropad/retro_right_stick.png) X | | I/K | ![](../image/retropad/retro_right_stick.png) Y | | Input descriptors for Keyboard - Port 4 | RetroPad Inputs | |-----------------------------------------|------------------------------------------------| | Backspace | ![](../image/retropad/retro_dpad_up.png) | | Backslash | ![](../image/retropad/retro_dpad_down.png) | | Semicolon | ![](../image/retropad/retro_dpad_left.png) | | Quote | ![](../image/retropad/retro_dpad_right.png) | | O | ![](../image/retropad/retro_select.png) | | P | ![](../image/retropad/retro_start.png) | | Slash | ![](../image/retropad/retro_x.png) | | Right Shift | ![](../image/retropad/retro_y.png) | | Right Ctrl | ![](../image/retropad/retro_b.png) | | Right Alt | ![](../image/retropad/retro_a.png) | | Left Bracket | ![](../image/retropad/retro_l1.png) | | Right Bracket | ![](../image/retropad/retro_r1.png) | | Comma | ![](../image/retropad/retro_l2.png) | | Period | ![](../image/retropad/retro_r2.png) | | Minus | ![](../image/retropad/retro_l3.png) | | Equals | ![](../image/retropad/retro_r3.png) | | Semicolon/Quote | ![](../image/retropad/retro_left_stick.png) X | | Backspace/Backslash | ![](../image/retropad/retro_left_stick.png) Y | | Left/Right Bracket | ![](../image/retropad/retro_right_stick.png) X | | Minus/Equals | ![](../image/retropad/retro_right_stick.png) Y | !!!tip Above are the default keyboard to RetroPad mappings for all 4 ports. Note that by using the Quick Menu, you can choose from various presets in the `Controls` > `Port # Controls` section. | Input descriptors for Emulated mouse | RetroPad Inputs | |--------------------------------------|------------------------------------------------| | Emulated Mouse Right Click | ![](../image/retropad/retro_l2.png) | | Emulated Mouse Left Click | ![](../image/retropad/retro_r2.png) | | Emulated Mouse X Axis | ![](../image/retropad/retro_right_stick.png) X | | Emulated Mouse Y Axis | ![](../image/retropad/retro_right_stick.png) Y | ## Keyboard | RetroKeyboard Inputs | Keyboard | |-------------------------------|--------------------| | Keyboard Backspace | Backspace | | Keyboard Tab | Tab | | Keyboard Return | Enter | | Keyboard Pause | Pause | | Keyboard Escape | Escape | | Keyboard Space | Space | | Keyboard ' | ' | | Keyboard , | , | | Keyboard . | . | | Keyboard / | / | | Keyboard 0 | 0 | | Keyboard 1 | 1 | | Keyboard 2 | 2 | | Keyboard 3 | 3 | | Keyboard 4 | 4 | | Keyboard 5 | 5 | | Keyboard 6 | 6 | | Keyboard 7 | 7 | | Keyboard 8 | 8 | | Keyboard 9 | 9 | | Keyboard ; | ; | | Keyboard - | - | | Keyboard = | = | | Keyboard [ | [ | | Keyboard \ | \ | | Keyboard ] | ] | | Keyboard ` | ` | | Keyboard a | a | | Keyboard b | b | | Keyboard c | c | | Keyboard d | d | | Keyboard e | e | | Keyboard f | f | | Keyboard g | g | | Keyboard h | h | | Keyboard i | i | | Keyboard j | j | | Keyboard k | k | | Keyboard l | l | | Keyboard m | m | | Keyboard n | n | | Keyboard o | o | | Keyboard p | p | | Keyboard q | q | | Keyboard r | r | | Keyboard s | s | | Keyboard t | t | | Keyboard u | u | | Keyboard v | v | | Keyboard w | w | | Keyboard x | x | | Keyboard y | y | | Keyboard z | z | | Keyboard Delete | Delete | | Keyboard Numpad 0 | Numpad 0 | | Keyboard Numpad 1 | Numpad 1 | | Keyboard Numpad 2 | Numpad 2 | | Keyboard Numpad 3 | Numpad 3 | | Keyboard Numpad 4 | Numpad 4 | | Keyboard Numpad 5 | Numpad 5 | | Keyboard Numpad 6 | Numpad 6 | | Keyboard Numpad 7 | Numpad 7 | | Keyboard Numpad 8 | Numpad 8 | | Keyboard Numpad 9 | Numpad 9 | | Keyboard Numpad . | Numpad . | | Keyboard Numpad / | Numpad / | | Keyboard Numpad * | Numpad * | | Keyboard Numpad - | Numpad - | | Keyboard Numpad + | Numpad + | | Keyboard Numpad Enter | Numpad Enter | | Keyboard Up | Up | | Keyboard Down | Down | | Keyboard Right | Left | | Keyboard Left | Right | | Keyboard Insert | Insert | | Keyboard Home | Home | | Keyboard End | End | | Keyboard Page Up | Page Up | | Keyboard Page Down | Page Down | | Keyboard F1 | F1 | | Keyboard F2 | F2 | | Keyboard F3 | F3 | | Keyboard F4 | F4 | | Keyboard F5 | F5 | | Keyboard F6 | F6 | | Keyboard F7 | F7 | | Keyboard F8 | F8 | | Keyboard F9 | F9 | | Keyboard F10 | F10 | | Keyboard F11 | F11 | | Keyboard F12 | F12 | | Keyboard Num Lock | Num Lock | | Keyboard Caps Lock | Caps Lock | | Keyboard Scroll Lock | Scroll Lock | | Keyboard Right Shift | Right Shift | | Keyboard Left Shift | Left Shift | | Keyboard Right Control | Right Control | | Keyboard Left Control | Left Control | | Keyboard Right Alt | Right Alt | | Keyboard Left Alt | Left Alt | | Keyboard Sys Req | Print Screen | ## Compatibility ### Boppin' If the game rapidly cycles through the main menu options indefinitely, it has to do with malfunctioning joystick calibration. try deleting the game's config file, `BOPPIN.CFG`, and then reconfiguring the game. To do so, go to the command line from the start menu, then type: ``` DEL BOPPIN.CFG SETUP.EXE BOPPIN.EXE ``` To fix this in-game, you need to go to the core options and fiddle around with the Emulated Performance setting until the cursor stops moving. Boppin' uses some form of joystick calibration which depends on the speed of the CPU. And it seems that once it has some form of calibration data, it saves that to its config file. So if you use the game pre-configured while running with different performance emulation (cycles) settings, it will have its joysticks off-calibrated and thus scrolling through the main menu (always holding up or down) or switching between the title screen and the menu (always holding left or right). [More info here](https://github.com/schellingb/dosbox-pure/issues/75#issuecomment-1115108702). ## External Links - [Official DOSBox Website](https://www.dosbox.com/) - [Official/Original DOSBox SourceForge Repository](https://sourceforge.net/projects/dosbox/) - [Libretro DOSBox Pure info file](https://github.com/libretro/libretro-super/blob/master/dist/info/dosbox_pure_libretro.info) ![#f03c15] - [Libretro DOSBox Pure GitHub Repository](https://github.com/schellingb/dosbox-pure) - [Report Libretro DOSBox Pure core Issues Here](https://github.com/schellingb/dosbox-pure/issues) ================================================ FILE: docs/library/doukutsu-rs.md ================================================ # doukutsu-rs *This article primarily outlines the retroarch-specific features of this core. For a general feature-list and how-to for d-rs, please see the readme in the [Upstream Repository](https://github.com/doukutsu-rs/doukutsu-rs/).*
![](../image/core/doukutsu-rs/drs-libretro.png)
## Background Doukutsu-rs *(often abbreviated d-rs)* is a modern and accurate re-implementation of the Cave Story Engine designed to be a drop-in replacement for all official and most fan ports, including: - CS Freeware - Cave Story+ - Cave Story Switch - Cave Story Wiiware - CSE2 - NXEngine-Evo The engine adds other Quality-of-life features like 2-player local multiplayer, lighting effects, and smooth motion interpolation. ## Requirements Currently, this core requires at least OpenGL 2 or OpenGLES 2 to run. On MacOS systems, it requires at least OpenGL 3 support. Supported platforms: - Windows - Linux - Mac OS *(at least openGL 3 required)* - Android - iOS ## How to start d-rs: D-rs does not ship with Cave Story data. To run it, you can either supply your own datafiles or use the "Content Downloader" (for Freeware only). For more information on how to get the files from your specific Cave Story install, see the [Upstream Repository readme](https://github.com/doukutsu-rs/doukutsu-rs/). ### Freeware Freeware files can be obtained from the [tribute site](https://www.cavestory.org/download/cave-story.php) or via the retroarch Content Downloader, in a similar manner to the NXEngine core: 1. Go to RetroArch's main menu screen and select "Online Updater". From there, select "Content Downloader". 2. In the list, there should be a folder labeled `Cave Story`. Select it, then select the `Cave Story (En).zip` file. The file should be downloaded and extracted to Retroarch's `Downloads` directory. 3. Go back to RetroArch's main menu screen. Select "Load Content", then navigate to `Downloads/Cave Story (En)/` and select `Doukutsu.exe`. 4. If given the choice on what core to run, choose `Cave Story (drs)`. The game should begin playing. ### Cave Story + The process for Cave Story plus is largely the same, but you have to supply your own datafiles. 1. Grab your CS+ install and place it where you can navigate to it from retroarch. 2. Navigate to the CS+ folder and select the `CaveStory+.exe` file. 3. If given the choice on what core to run, choose `Cave Story (drs)`. The game should begin playing. ### Cave Story + (Switch edition / Wiiware edition) These versions of Cave Story don't have an executable bundled with the `data` folder. D-rs can load this just fine, but it needs to know *where* to find it, which requires the creation of a "dummy" executable next to the data folder.
![](../image/core/doukutsu-rs/dummy-target.png)
1. Grab your CS-Switch or CS-Wiiware install and place it where you can navigate to it from retroarch. 2. In the folder that contains the `data` folder *(not INSIDE the data folder, but next to it)*, create an empty file with the `.exe` extension. Name doesn't matter, (example: `Target.exe`) 3. Navigate to the containing folder and select the target file you just made. 4. If given the choice on what core to run, choose `Cave Story (drs)`. The game should begin playing. ## Extensions **With the exception of Freeware cave story**, d-rs mainly uses the target file as a reference to figure out where the data folder is. *(since at the time of writing, retroarch can't load a folder directly through the GUI)* If the core is loading from Freeware for the first time, it will open the file in order to dump its internal assets into the `data` directory. After this, the executable isn't needed beyond use as a starting "target" for the core. For CS+, Wiiware, or NXEngine, placing an empty "target" file in the same directory as the `data` folder with one of these extensions will load the game. - .so - .dll - .exe The info file source can be found here: https://github.com/libretro/libretro-super/blob/master/dist/info/doukutsu_rs_libretro.info ## Frontend Features | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | X | | States | X | | Rewind | X | | Netplay | X | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | X | | RetroArch Cheats | X | | Native Cheats | ✔ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | X | | Rumble | ✔ | | Sensors | X | | Camera | X | | Location | X | | Subsystem | X | | [Softpatching](../guides/softpatching.md) | X | | Disk Control | X | | Username | X | | Language | X | | Crop Overscan | X | | LEDs | X | | Fast Forward | X | | Slow-mo | ✔ | ## Directories D-rs will modify the following files/folders: - `~/data` - *(only with freeware)*, will be populated with Cave Story's internal assets the first time the game is launched (things like music and credit images). - `~/user` - If this folder already exists (I.E. continuing a game that was started on another port of d-rs), d-rs will use this directory instead of `RetroArch/saves/d-rs`. - `RetroArch/saves/d-rs` - game saves, internal settings, and operation logs will be stored in this folder. ## Geometry and timing D-rs separates in-game time from screen refresh rate. The game can be either set to run at 50 TPS (mimicking Freeware CS) or 60 FPS (mimicking CS+). Screen drawing varies depending on hardware capability, but is typically around 60 FPS. Depending on the `Core Options` (see below), the game's screen ratio can be changed. ## Core options - **Internal upscaling factor** - The size of the "screen" that the core thinks it's drawing to. Larger resolutions provide smoother visuals. For CS+, a minimum scale of x2 is needed to retain all image detail. `2x (CS+, default)|1x (freeware, fastest)|3x (smoother motion)|4x (smoothest motion)`, - **Screen Ratio** - Shape of the "screen" that the core thinks it's drawing to. Original CS is 4:3, but d-rs supports widescreen. `4:3 (original)|16:9 (switch)|16:10|21:9` - **Debug Outlines** - Draw onscreen markers to show where entities are and what they are colliding with. `Disabled|Enabled` - **Show FPS** - Show in-game TPS and FPS. `Disabled|Enabled` - **Show Debug GUI** - Show the IMGUI debug menu *(no real use at the moment; mouse input is disabled)*. `Disabled|Enabled` - **GOD Mode (Invincibility)** - Player cannot take damage. `Disabled|Enabled` - **Infinite Booster** - Gives the player the jetpack without a fuel limit. `Disabled|Enabled` - **Noclip** - Allows the player to float through the map without tile or NPC collision. `Disabled|Enabled` - **More Rust** - Turns Sue into the d-rs mascot (![](../image/core/doukutsu-rs/more-rust.png){ width="16" height="16" }). `Disabled|Enabled` ## User 1-2 device types The d-rs core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): - **Retropad (Port 1)** - Player 1 controls. - **Retropad (Port 2)** - Player 2 controls. These controls can be re-assigned in both the retroarch frontend and in the core itself. ## Rumble If the frontend supports rumble and is paired with a controller that has the capability, d-rs will provide vibration feedback during screen shakes and other various in-game events. Rumble can also be disabled within the core's settings menu. ## Joypad *Note: These buttons can be re-bound in the frontend as well as within the core.* | RetroPad Inputs | Input descriptors | |------------------------------------------------|--------------------------------| | ![](../image/retropad/retro_b.png) | Shoot | | ![](../image/retropad/retro_a.png) | Jump | | ![](../image/retropad/retro_y.png) | Inventory/Cutscene Fast Forward| | ![](../image/retropad/retro_start.png) | Pause | | ![](../image/retropad/retro_x.png) | Show/Hide Map | | ![](../image/retropad/retro_dpad_up.png) | Aim up | | ![](../image/retropad/retro_dpad_down.png) | Interact/Aim down | | ![](../image/retropad/retro_dpad_left.png) | Move Left | | ![](../image/retropad/retro_dpad_right.png) | Move Right | | ![](../image/retropad/retro_l1.png) | Previous Weapon | | ![](../image/retropad/retro_r1.png) | Next Weapon | | ![](../image/retropad/retro_r2.png) | Strafe | | ![](../image/retropad/retro_l3.png) | Move (d-pad equivalent) | ## External Links - [Official doukutsu-rs source (GitHub)](https://github.com/doukutsu-rs/doukutsu-rs) - [Official doukutsu-rs website](https://doukutsu-rs.github.io/) --- - [Libretro port of d-rs (backend)](https://github.com/DrGlaucous/doukutsu-rs-nm/tree/retroarch-dev) - [Libretro port of d-rs (interface layer)](https://github.com/DrGlaucous/doukutsu-rs-libretro/) --- - [d-rs discord server](https://discord.gg/fbRsNNB) ## (Related cores) - [NXEngine](nxengine.md) ================================================ FILE: docs/library/dummy.md ================================================ # Dummy core ## Background 'Load Dummy on Core Shutdown' option in RetroArch's Core settings. Some cores might have a shutdown feature. If enabled, it will prevent the core from shutting RetroArch down. Instead, it loads a dummy core. ### Author/License The Dummy core has been authored by - The RetroArch Team The Dummy core is licensed under - MIT A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## External Links - [Libretro Dummy core Github Repository](https://github.com/libretro/RetroArch/tree/master/cores) ================================================ FILE: docs/library/easyrpg.md ================================================ # RPG Maker 2000/2003 (EasyRPG) ## Background EasyRPG Player is a game interpreter to play RPG Maker 2000, 2003 and EasyRPG games. It uses the LCF parser library (liblcf) to read RPG Maker game data. EasyRPG Player is part of the EasyRPG Project. More information is available at the project website: [https://easyrpg.org/](https://easyrpg.org/) ### Author/License The EasyRPG core has been authored by - EasyRPG team The EasyRPG core is licensed under - [GPLv3](https://github.com/libretro/easyrpg-libretro/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the EasyRPG core have the following file extensions: - .ldb - .zip - .easyrpg ### RTP files You must download the RTP2000 and RTP2003 from [here](https://www.rpgmakerweb.com/run-time-package). They are exe/zip files but can be extracted with e.g. 7zip. Create `rtp` folder in `system` folder. Put the extracted data in "rtp/2000" and "rtp/2003" to `system/rtp` accordingly. | | | | | | |---|---|---|---|---| | retroarch | system | rtp | 2000 | | | | | | 2003 | | ## Databases RetroArch database(s) that are associated with the EasyRPG core: - [RPG Maker](https://github.com/libretro/libretro-database/blob/master/rdb/RPG%20Maker.rdb) - [RPG Maker thumbnails](https://github.com/libretro-thumbnails/RPG_Maker) ## Features Frontend-level settings or features that the EasyRPG core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The EasyRPG core's internal core name is 'EasyRPG' The EasyRPG core saves/loads to/from these directories. **Loaded content's directory** - Save##.lsd (Save files) - Save##.dyn (Additional save file data used by some games) - Save.lgs (Global save data used by some games) - easyrpg_log.txt (EasyRPG log file) **Frontend's system directory** - easyrpg-player/config.ini (configuration of the engine) ### Geometry and timing - The EasyRPG core's core provided FPS is (FPS) - The EasyRPG core's core provided sample rate is 44100 Hz - The EasyRPG core's core provided aspect ratio is (Ratio) ## Controllers The EasyRPG core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. There's no reason to switch to this. - **RetroPad** - Joypad - Stay on this. - RetroPad w/Analog - Joypad - Same as RetroPad. There's no reason to switch to this. ### Controller tables #### Joypad | RetroPad Inputs | EasyRPG core inputs | |------------------------------------------------|---------------------------| | ![](../image/retropad/retro_dpad_up.png) | Up | | ![](../image/retropad/retro_dpad_down.png) | Down | | ![](../image/retropad/retro_dpad_left.png) | Left | | ![](../image/retropad/retro_dpad_right.png) | Right | | ![](../image/retropad/retro_a.png) | Decision | | ![](../image/retropad/retro_b.png) | Cancel | | ![](../image/retropad/retro_x.png) | Cancel | | ![](../image/retropad/retro_y.png) | Shift | | ![](../image/retropad/retro_l3.png) | Number 0 | | ![](../image/retropad/retro_right_stick.png) | Number 1 | | ![](../image/retropad/retro_right_stick.png) | Number 2 | | ![](../image/retropad/retro_right_stick.png) | Number 3 | | ![](../image/retropad/retro_right_stick.png) | Number 4 | | ![](../image/retropad/retro_r3.png) | Number 5 | | ![](../image/retropad/retro_right_stick.png) | Number 6 | | ![](../image/retropad/retro_right_stick.png) | Number 7 | | ![](../image/retropad/retro_right_stick.png) | Number 8 | | ![](../image/retropad/retro_right_stick.png) | Number 9 | | ![](../image/retropad/retro_start.png) | Settings Menu | | ![](../image/retropad/retro_select.png) | Reset | | ![](../image/retropad/retro_r2.png) | Fast Forward (x3) | | ![](../image/retropad/retro_r2.png) | Fast Forward (x10) | | ![](../image/retropad/retro_l2.png) | Debug Menu (Test Play mode only) | | ![](../image/retropad/retro_l2.png) | Debug Through (Test Play mode only) | | ![](../image/retropad/retro_r1.png) | Debug Save (Test Play mode only) | | ![](../image/retropad/retro_l1.png) | Debug Abort Event (Test Play mode only) | ## External Links - [Official EasyRPG Website](https://easyrpg.org/) - [Official EasyRPG Github Repository](https://github.com/EasyRPG/Player) - [Libretro EasyRPG Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/easyrpg_libretro.info) - [Libretro EasyRPG Github Repository](https://github.com/libretro/easyrpg-libretro) - [Report Libretro EasyRPG Core Issues Here](https://github.com/libretro/easyrpg-libretro/issues) ## (Related cores) - [RPG Maker XP/VX/VX Ace (mkxp-z)](mkxp-z.md) ================================================ FILE: docs/library/ecwolf.md ================================================ # Wolfenstein 3D/Spear of Destiny/Super 3D Noah’s Ark (ECWolf) *WIP* ## Background ECWolf is a port of the Wolfenstein 3D engine based of Wolf4SDL. It combines the original Wolfenstein 3D engine with the user experience of ZDoom to create the most user and mod author friendly Wolf3D source port. Like ZDoom, ECWolf aims to support all games which use the Wolfenstein 3D engine including Blake Stone (coming in ECWolf 3.0), Corridor 7, Operation Body Count, Rise of the Triad, and Super 3D Noah's Ark. ECWolf will also support Macintosh Wolfenstein 3D along with all of its user created missions (coming in ECWolf 2.0). - phcoder The ECWolf core is licensed under - [BSD/LGPL]() A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). - Single binary runs all supported games. (Wolfenstein 3D, Spear of Destiny, ...) - Full support for high resolution modes with aspect ratio correction including wide screen support. - Modern control schemes (WASD + mouse). - Mac Wolf/S3DNA/ROTT style automap. - Unlimited save slots. - This is actually based on the Wolf3D engine instead of a recreation or forcing into a more modern engine. - Software rendered using the same 8-bit ray casting. ## Extensions Content that can be loaded by the ECWolf core have the following file extensions: - wl6 - n3d - sod - sdm - wl1 - pk3 - exe ## Databases RetroArch database(s) that are associated with the ECWolf core: - [ECWolf](https://github.com/libretro/libretro-database/blob/master/rdb/Wolfenstein%203D.rdb) ## BIOS ECWolf does require BIOS (bootrom) files to work. - ecwolf.pk3 ## Features | Feature | Supported | |-------------------|:---------:| | Restart | ✕ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | Softpatching | ✕ | | Disk Control | ✕ | | Username | ✕ | | Crop Overscan (in RetroArch's Video settings) | ✕ | ### Directories The ECWolf core's internal core name is `ecwolf`. ### Core provided aspect ratio ECWolf's core provided aspect ratio is 16:10. ## Core options ## Controllers ### Device types The ECWolf core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): #### User 1 - 1 device types - None - Input disabled. - **RetroPad** - Joypad - RetroPad w/Analog - Joypad - **There is no reason to switch to this.** ### Controller tables #### Joypad and analog device type table | RetroPad Inputs | User 1 input descriptors | |------------------------------------------------|--------------------------| | ![](../image/retropad/retro_dpad_up.png) | Move Forward | | ![](../image/retropad/retro_dpad_down.png) | Move Backward | | ![](../image/retropad/retro_dpad_left.png) | Turn Left | | ![](../image/retropad/retro_dpad_right.png) | Turn Right | | ![](../image/retropad/retro_l1.png) | Strafe Left | | ![](../image/retropad/retro_r1.png) | Strafe Right | | ![](../image/retropad/retro_a.png) | Fire | | ![](../image/retropad/retro_b.png) | Use | | ![](../image/retropad/retro_x.png) | Run | | ![](../image/retropad/retro_y.png) | Show Status | | ![](../image/retropad/retro_select.png) | Map | | ![](../image/retropad/retro_l2.png) | Previous Weapon | | ![](../image/retropad/retro_r2.png) | Next Weapon | | ![](../image/retropad/retro_start.png) | Pause | | ![](../image/retropad/retro_left_stick.png) X | Strafe Left/Right | | ![](../image/retropad/retro_left_stick.png) Y | Move Forward/Backward | | ![](../image/retropad/retro_right_stick.png) X | Turn Left/Right | ## External Links - [Libretro ECWolf Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/ecwolf_libretro.info) - [Libretro ECWolf Github Repository](https://github.com/libretro/ecwolf) - [Report ECWolf Core Issues Here](https://github.com/libretro/ecwolf/issues) ================================================ FILE: docs/library/eightyone.md ================================================ # ZX81 (EightyOne) *WIP* ## Background 81-libretro is an work in progress port of the EightyOne (a.k.a. THE Sinclair Emulator) to libretro. The classic ZX81 games are all over the Internet, but check the colorized folder for games with Chroma 81 support. There are also many original games for the Zeddy, check Bob's Stuff for some high quality games. The EightyOne core has been authored by - Michael D Wynne The EightyOne core is licensed under - [GPLv3](https://github.com/libretro/81-libretro/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). EightyOne emulates a number of ZX80, ZX81, clones, and other computers based on the same hardware: - Sinclair ZX80 - Sinclair ZX81 - Timex TS1000 - Timex TS1500 - Lambda 8300 - Ringo R470 - MicroDigital TK85 - Jupiter ACE However, 81-libretro only emulates the Sinclair ZX81 with 16Kb RAM for now. Other machines will be added as time permits. Push requests are welcome. The port correctly loads and runs some many games I have around in the p format. tzx format is also supported. EightyOne also emulates some ZX Spectrum machines, but those were left out of this core on purpose. ## Extensions Content that can be loaded by the EightyOne core have the following file extensions: - .p - .tzx - .t81 ## Databases RetroArch database(s) that are associated with the EightyOne core: - [Sinclair - ZX 81](https://github.com/libretro/libretro-database/blob/master/rdb/Sinclair%20-%20ZX%2081.rdb) ## Features RetroArch-level settings or features that the EightyOne core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✕ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✕ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The EightyOne core's directory name is 'EightyOne' The EightyOne core saves/loads to/from these directories. **RetroArch's State directory** - 'content-name'.state# (State) ### Geometry and timing - The EightyOne core's core provided FPS is 50 - The EightyOne core's core provided sample rate is 44100 Hz - The EightyOne core's core provided aspect ratio is (Ratio) ### Auto-configuration Since configuring the core for each game can be a tedious task, the EightyOne core features auto-configuration. Games that support auto-configuration are listed in the [src/gamedb/gamedb.json file](https://github.com/libretro/81-libretro/blob/master/src/gamedb/gamedb.json), along with some information and the configuration required to play them. Currently, there's no way to change the auto-configuration settings short of recompiling the core after making the changes. If you feel the provided auto-configuration could be better or has bugs, please open an [issue](https://github.com/libretro/81-libretro/issues). ### Colorization Colorization works by loading a program prior to loading the game. This program will check if the Chroma 81 expansion is installed, and, if it is, configures the colors of the ZX81 characters, and then loads the original game, which runs unaware that it's playing with colors. Since the EightyOne core can't load arbitrary programs from the file system, the colorization program and the game must exist in the same file. ## Core options The EightyOne core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Tape Fast Load** (Off/**On**) Instantly loads files if enabled, or disable it to see the moving horizontal lines while the game loads. - **8K-16K Contents** (**auto**/ROM shadow/RAM/dK'tronics 4K Graphics ROM + 4K RAM) Selects the contents of memory addresses between 8192 and 16383, a shadow copy of the ROM, 8K of RAM, or [dK'tronics 4K ROM plus 4K of RAM](http://www.fruitcake.plus.com/Sinclair/ZX81/Chroma/ChromaInterface_Software_CharacterSetROM.htm). - **High Resolution** (**auto**/none/WRX) Enables WRX high resolution. - **Emulate Chroma 81** (**auto**/Off/On) Enable the [Chroma 81](http://www.fruitcake.plus.com/Sinclair/ZX81/Chroma/ChromaInterface.htm) interface (colorization). ??? note "Emulate Chroma 81 - auto/On" ![](../image/core/eightyone/chroma_on.png) ??? note "Emulate Chroma 81 - Off" ![](../image/core/eightyone/chroma_off.png) - **Video Presets** (**clean**/tv/noisy) Change how the video is emulated (if Chroma 81 is enabled, the video is set to "clean" regardless of this option). ??? note "Video Presets - clean" ![](../image/core/eightyone/clean.png) ??? note "Video Presets - tv" ![](../image/core/eightyone/tv.png) ??? note "Video Presets - noisy" ![](../image/core/eightyone/clean.png) - **Sound emulation** (**auto**/none/Zon X-81) Enables sound emulation. - **Joypad Left mapping** (**auto**/default/new line/shift/space/./0/1/2/3/4/5/6/7/8/9/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z) Maps this joypad button to a keyboard key, defaults are the cursor keys for the directional pad and '0' to all the other buttons. - **Joypad Right mapping** (**auto**/default/new line/shift/space/./0/1/2/3/4/5/6/7/8/9/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z) Maps this joypad button to a keyboard key, defaults are the cursor keys for the directional pad and '0' to all the other buttons. - **Joypad Up mapping** (**auto**/default/new line/shift/space/./0/1/2/3/4/5/6/7/8/9/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z) Maps this joypad button to a keyboard key, defaults are the cursor keys for the directional pad and '0' to all the other buttons. - **Joypad Down mapping** (**auto**/default/new line/shift/space/./0/1/2/3/4/5/6/7/8/9/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z) Maps this joypad button to a keyboard key, defaults are the cursor keys for the directional pad and '0' to all the other buttons. - **Joypad A button mapping** (**auto**/default/new line/shift/space/./0/1/2/3/4/5/6/7/8/9/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z) Maps this joypad button to a keyboard key, defaults are the cursor keys for the directional pad and '0' to all the other buttons. - **Joypad B button mapping** (**auto**/default/new line/shift/space/./0/1/2/3/4/5/6/7/8/9/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z) Maps this joypad button to a keyboard key, defaults are the cursor keys for the directional pad and '0' to all the other buttons. - **Joypad X button mapping** (**auto**/default/new line/shift/space/./0/1/2/3/4/5/6/7/8/9/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z) Maps this joypad button to a keyboard key, defaults are the cursor keys for the directional pad and '0' to all the other buttons. - **Joypad Y button mapping** (**auto**/default/new line/shift/space/./0/1/2/3/4/5/6/7/8/9/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z) Maps this joypad button to a keyboard key, defaults are the cursor keys for the directional pad and '0' to all the other buttons. - **Joypad L button mapping** (**auto**/default/new line/shift/space/./0/1/2/3/4/5/6/7/8/9/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z) Maps this joypad button to a keyboard key, defaults are the cursor keys for the directional pad and '0' to all the other buttons. - **Joypad R button mapping** (**auto**/default/new line/shift/space/./0/1/2/3/4/5/6/7/8/9/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z) Maps this joypad button to a keyboard key, defaults are the cursor keys for the directional pad and '0' to all the other buttons. - **Joypad L2 button mapping** (**auto**/default/new line/shift/space/./0/1/2/3/4/5/6/7/8/9/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z) Maps this joypad button to a keyboard key, defaults are the cursor keys for the directional pad and '0' to all the other buttons. - **Joypad R2 button mapping** (**auto**/default/new line/shift/space/./0/1/2/3/4/5/6/7/8/9/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y/z) Maps this joypad button to a keyboard key, defaults are the cursor keys for the directional pad and '0' to all the other buttons. - **Transparent Keyboard Overlay** (Off/**On**) If the keyboard overlay is transparent or opaque. ??? note "Transparent Keyboard Overlay - On" ![](../image/core/eightyone/trans_on.png) ??? note "Transparent Keyboard Overlay - Off" ![](../image/core/eightyone/trans_off.png) - **Time to Release key in ms** (**100**/300/500/1000) How many milliseconds to wait before releasing the key pressed using the keyboard overlay. ## Controllers The EightyOne core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Input disabled. - **RetroPad** - Joypad - Cursor Joystick - Joypad - Switch to this for joypad inputs. ### User 2 device types - None - Input disabled. - **RetroPad** - Joypad - Sinclair Keyboard - Keyboard - Switch to this for keyboard inputs. Switch the User 1 device type to none if the correct keyboard inputs aren't being read. ### Controller tables #### Joypad !!! attention Use the Joypad mapping core options to configure the Cursor Joystick inputs. | User 1 Remap descriptors | RetroPad Inputs | Cursor Joystick | |-------------------------------|----------------------------------------------|--------------------------| | | ![](../image/retropad/retro_b.png) | Joypad B button mapping | | | ![](../image/retropad/retro_y.png) | Joypad Y button mapping | | | ![](../image/retropad/retro_select.png) | Keyboard overlay | | | ![](../image/retropad/retro_dpad_up.png) | Joypad Up mapping | | | ![](../image/retropad/retro_dpad_down.png) | Joypad Down mapping | | | ![](../image/retropad/retro_dpad_left.png) | Joypad Left mapping | | | ![](../image/retropad/retro_dpad_right.png) | Joypad Right mapping | | | ![](../image/retropad/retro_a.png) | Joypad A button mapping | | | ![](../image/retropad/retro_x.png) | Joypad X button mapping | | | ![](../image/retropad/retro_l1.png) | Joypad L button mapping | | | ![](../image/retropad/retro_r1.png) | Joypad R button mapping | | | ![](../image/retropad/retro_l2.png) | Joypad L2 button mapping | | | ![](../image/retropad/retro_r2.png) | Joypad R2 button mapping | #### Keyboard | RetroKeyboard Inputs | Sinclair Keyboard | |------------------------------|--------------------| | Keyboard Backspace | VK_BACK | | Keyboard Tab | VK_TAB | | Keyboard Clear | VK_CLEAR | | Keyboard Return | VK_RETURN | | Keyboard Pause | VK_PAUSE | | Keyboard Escape | VK_ESCAPE | | Keyboard Space | VK_SPACE | | Keyboard Comma , | VK_COMMA | | Keyboard Delete | VK_DELETE | | Keyboard Keypad 0 | VK_NUMPAD0 | | Keyboard Keypad 1 | VK_NUMPAD1 | | Keyboard Keypad 2 | VK_NUMPAD2 | | Keyboard Keypad 3 | VK_NUMPAD3 | | Keyboard Keypad 4 | VK_NUMPAD4 | | Keyboard Keypad 5 | VK_NUMPAD5 | | Keyboard Keypad 6 | VK_NUMPAD6 | | Keyboard Keypad 7 | VK_NUMPAD7 | | Keyboard Keypad 8 | VK_NUMPAD8 | | Keyboard Keypad 9 | VK_NUMPAD9 | | Keyboard Keypad Period . | VK_DECIMAL | | Keyboard Keypad Divide / | VK_DIVIDE | | Keyboard Keypad Multiply * | VK_MULTIPLY | | Keyboard Keypad Minus - | VK_SUBTRACT | | Keyboard Keypad Plus + | VK_ADD | | Keyboard Up | VK_UP | | Keyboard Down | VK_DOWN | | Keyboard Right | VK_RIGHT | | Keyboard Left | VK_LEFT | | Keyboard Insert | VK_INSERT | | Keyboard Home | VK_HOME | | Keyboard End | VK_END | | Keyboard Page Up | VK_PRIOR | | Keyboard Page Down | VK_NEXT | | Keyboard F1 | VK_F1 | | Keyboard F2 | VK_F2 | | Keyboard F3 | VK_F3 | | Keyboard F4 | VK_F4 | | Keyboard F5 | VK_F5 | | Keyboard F6 | VK_F6 | | Keyboard F7 | VK_F7 | | Keyboard F8 | VK_F8 | | Keyboard F9 | VK_F9 | | Keyboard F10 | VK_F10 | | Keyboard F11 | VK_F11 | | Keyboard F12 | VK_F12 | | Keyboard F13 | VK_F13 | | Keyboard F14 | VK_F14 | | Keyboard F15 | VK_F15 | | Keyboard Num Lock | VK_NUMLOCK | | Keyboard Caps Lock | VK_CAPITAL | | Keyboard Scroll Lock | VK_SCROLL | | Keyboard Right Shift | VK_SHIFT | | Keyboard Left Shift | VK_SHIFT | | Keyboard Right Control | VK_CONTROL | | Keyboard Left Control | VK_CONTROL | | Keyboard Right Alt | VK_MENU | | Keyboard Left Alt | VK_MENU | | Keyboard Print | VK_SNAPSHOT | ## External Links - [Libretro EightyOne Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/81_libretro.info) - [Libretro EightyOne Github Repository](https://github.com/libretro/81-libretro) - [Report Libretro EightyOne Core Issues Here](https://github.com/libretro/81-libretro/issues) - [Official EightyOne Sourceforge Repository]((https://sourceforge.net/projects/eightyone-sinclair-emulator/)) ================================================ FILE: docs/library/emuscv.md ================================================ # Super Cassette Vision (EmuSCV) *Not Finished* ## Background Super Cassette Vision is a home video game console made by EPOCH CO. and released in Japan on July 17, 1984 and released in Europe (France only) later in 1984 under the YENO brand. The EmuSCV core has been authored by: - MARCONATO Maxime - TAKEDA Toshiya The EmuSCV core is licensed under [GPLv3](https://github.com/libretro/). A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the EmuSCV core have the following file extensions: - `.cart` (Native) - `.bin` - `.rom` Supported ROMs extensions: .CART (native), .BIN, .ROM, .0 (.1, .2, .3) and Zipped Roms (the name of the rom must be the same as the ZIP archive). All ROMs can be stored in a 1 file ROM (.CART, .BIN, .ROM or .0). Large ROMs can be stored in multiple files (.0, .1, .2, .3). ## Features Frontend-level settings or features that the EmuSCV core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | - | | States | - | | Rewind | - | | Netplay | x | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | x | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | x | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | x | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Geometry and timing - The EmuSCV core's core provided FPS is 60. - The EmuSCV core's core provided sample rate is 48000/00 Hz. - The EmuSCV core's base width is 960. - The EmuSCV core's base height is 720. - The EmuSCV core's core provided aspect ratio is 4:3. ## Usage Load any supported content file. Content type will be autodetected, and if possible, started. ## Core options The EmuSCV core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - CONSOLE (**AUTO**|EPOCH|YENO|EPOCHLADY) - forced sleep in main thread for lower CPU use - DISPLAY (**AUTO**|EMUSCV|EPOCH|YENO) - PIXELASPECT (**AUTO**|RECTANGULAR|SQUARE) - enable in case of performance problems (has some ## Control device types ## Joypad ## Keyboard ## BIOS EmuSCV require a Super Cassette Vision BIOS to run. There is only one version of the BIOS that can use diferent names: - upd7801g.s01 (standard) - upd7801g.bin - upd7801g.bios - bios.rom - bios.bin MD5: 635a978fd40db9a18ee44eff449fc126 The MD5 Checksum control for the BIOS can be disabled in core options to permit use of custom BIOS. ## External Links ================================================ FILE: docs/library/emux_chip8.md ================================================ # CHIP-8 (Emux) **This core currently doesn't start so this documentation will remain incomplete until it is fixed.** ## Contribute to this documentation In order to propose improvements to this document, [visit it's corresponding source page on github](https://github.com/libretro/docs/tree/master/docs/library/emux_chip8.md). Changes are proposed using "Pull Requests." ## Background Emux is a cross-platform emulator project with a goal of emulating multiple kinds of machines related to gaming, such as consoles or arcades. Its philosophy is very much inspired by the Linux kernel (hence the name), which brilliantly manages to support multiple machines while keeping drivers entirely platform-independent. Emux is designed in the same way, keeping a code base of CPUs and controllers separate from machines. ### How to get and install the Emux CHIP-8 core: 1. Start up RetroArch. Inside the main menu, go to 'Online Updater'. 2. Just to make sure we have the latest info files, select 'Update Core Info FIles'. Wait until this is done. Then, select 'Core Downloader'. 3. Browse through the list and select 'CHIP-8 (Emux)'. After this has finished downloading, the core should now be ready for use! ### Authors - Sebastien Ronsse ## License A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). - [GPLv2](https://github.com/libretro/emux/blob/master/COPYING) ## Extensions Content that can be loaded by the Emux CHIP-8 core have the following file extensions: - .ch8 - .bin - .rom ## Features | Feature | Supported | |-------------------|:---------:| | Saves | - | | States | - | | Rewind | - | | Netplay | - | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | - | | RetroArch Cheats | - | | Native Cheats | - | | Controllers | - | | Remapping | - | | Multi-Mouse | - | | Rumble | - | | Sensors | - | | Camera | - | | Location | - | | Subsystem | - | | Softpatching | - | ### Saves/States The Emux CHIP-8 core's directory name is 'emux (chip8)' Awaiting description. ## Core options Awaiting description. ## Controllers Awaiting description. ### Device types Awaiting description. ### Controllers graph Awaiting description. ## External Links - [Libretro Emux CHIP-8 Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/emux_chip8_libretro.info) - [Libretro Emux CHIP-8 Github Repository](https://github.com/libretro/emux) - [Report Libretro Emux CHIP-8 Core Issues Here](https://github.com/libretro/libretro-meta/issues) - [Official Emux CHIP-8 Github Repository](https://github.com/sronsse/emux) ## CHIP-8 - [XO-CHIP/CHIP-8 (JAXE)](jaxe.md) ================================================ FILE: docs/library/emux_gb.md ================================================ # Game Boy/Game Boy Color (Emux GB) *WIP* ## Background Emux is a cross-platform emulator project with a goal of emulating multiple kinds of machines related to gaming, such as consoles or arcades. Its philosophy is very much inspired by the Linux kernel (hence the name), which brilliantly manages to support multiple machines while keeping drivers entirely platform-independent. Emux is designed in the same way, keeping a code base of CPUs and controllers separate from machines. The Emux GB core has been authored by - Sebastien Ronsse The Emux GB core is licensed under - [GPLv2](https://github.com/libretro/emux/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Emux GB core have the following file extensions: - .gb - .bin - .rom ## Databases RetroArch database(s) that are associated with the Emux GB core: - [Nintendo - Game Boy](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Game%20Boy.rdb) - [Nintendo - Game Boy Color](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Game%20Boy%20Color.rdb) ## BIOS Required or optional firmware files go in RetroArch's system directory. | Filename | Description | md5sum | |:-------------:|:------------------------------:|:--------------------------------:| | dmg_boot.bin | Game Boy Boot ROM - Required | 32fbbd84168d3482956eb3c5051637f5 | ## Features RetroArch-level settings or features that the Emux GB core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✕ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✕ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | Softpatching | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | ### Directories The Emux GB core's directory name is 'emux (gb)' ### Geometry and timing - The Emux GB core's internal FPS is (FPS) - The Emux GB core's internal sample rate is (Rate) - The Emux GB core's core provided aspect ratio is (Ratio) ## Controllers ### Device types The Emux GB core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): #### User 1 device types - None - Doesn't disable input. - **RetroPad** - Joypad - RetroPad w/Analog - Joypad - There is no reason to switch to this. ### Controller tables #### Joypad and analog device type table | User 1 Input descriptors | RetroPad Inputs | RetroPad | |-------------------------------|----------------------------------------------|--------------------| | | ![](../image/retropad/retro_b.png) | B | | | ![](../image/retropad/retro_select.png) | Select | | | ![](../image/retropad/retro_start.png) | Start | | | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | | | ![](../image/retropad/retro_a.png) | A | ## Compatibility Awaiting description. ## External Links - [Libretro Emux GB Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/emux_gb_libretro.info) - [Libretro Emux GB Github Repository](https://github.com/libretro/emux) - [Report Libretro Emux GB Core Issues Here](https://github.com/libretro/libretro-meta/issues) - [Official Emux GB Github Repository](https://github.com/sronsse/emux) ### See also #### Nintendo - Game Boy (+ Color) - [Nintendo - Game Boy / Color (Gambatte)](gambatte.md) - [Nintendo - Game Boy / Color (Gearboy)](gearboy.md) - [Nintendo - Game Boy / Color (SameBoy)](sameboy.md) - [Nintendo - Game Boy / Color (TGB Dual)](tgb_dual.md) - [Nintendo - Game Boy Advance (mGBA)](mgba.md) - [Nintendo - Game Boy Advance (VBA-M)](vba_m.md) - [Nintendo - SNES / Famicom (higan Accuracy)](higan_accuracy.md) - [Nintendo - SNES / Famicom (nSide Balanced)](nside_balanced.md) - [Nintendo - SNES / Famicom (Mesen-S)](mesen-s.md) ================================================ FILE: docs/library/emux_nes.md ================================================ # Nintendo - NES / Famicom (Emux NES) ## Background Emux is a cross-platform emulator project with a goal of emulating multiple kinds of machines related to gaming, such as consoles or arcades. Its philosophy is very much inspired by the Linux kernel (hence the name), which brilliantly manages to support multiple machines while keeping drivers entirely platform-independent. Emux is designed in the same way, keeping a code base of CPUs and controllers separate from machines. ### Author/License The Emux NES core has been authored by - Sebastien Ronsse The Emux NES core is licensed under - [GPLv2](https://github.com/libretro/emux/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Emux NES core have the following file extensions: - .nes - .bin - .rom ## Databases RetroArch database(s) that are associated with the Emux NES core: - [Nintendo - Nintendo Entertainment System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%20Entertainment%20System.rdb) ## Features Frontend-level settings or features that the Emux NES core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✕ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✕ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Emux NES core's internal core name is 'emux (nes)' ### Geometry and timing - The Emux NES core's core provided FPS is (FPS) - The Emux NES core's core provided sample rate is (Rate) - The Emux NES core's core provided aspect ratio is (Ratio) ## Controllers The Emux NES core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 - 2 device types - None - Doesn't disable input. There's no reason to switch to this. - **RetroPad** - Joypad - Stay on this. - RetroPad w/Analog - Joypad - Same as RetroPad. There's no reason to switch to this. ### Controller tables #### Joypad ![](../image/controller/nes.png) | RetroPad Inputs | Emux NES core Inputs | |----------------------------------------------|----------------------| | ![](../image/retropad/retro_b.png) | B | | ![](../image/retropad/retro_select.png) | Select | | ![](../image/retropad/retro_start.png) | Start | | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | | ![](../image/retropad/retro_a.png) | A | ## Compatibility Awaiting description. ## External Links - [Official Emux GB Github Repository](https://github.com/sronsse/emux) - [Libretro Emux GB Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/emux_gb_libretro.info) - [Libretro Emux GB Github Repository](https://github.com/libretro/emux) - [Report Libretro Emux GB Core Issues Here](https://github.com/libretro/libretro-meta/issues) ### See also #### Nintendo - Nintendo Entertainment System - [Nintendo - NES / Famicom (bnes)](bnes.md) - [Nintendo - NES / Famicom (FCEUmm)](fceumm.md) - [Nintendo - NES / Famicom (Mesen)](mesen.md) - [Nintendo - NES / Famicom (Nestopia)](nestopia.md) - [Nintendo - NES / Famicom (QuickNES)](quicknes.md) ================================================ FILE: docs/library/emux_sms.md ================================================ # Sega - Master System (Emux SMS) ## Background Emux is a cross-platform emulator project with a goal of emulating multiple kinds of machines related to gaming, such as consoles or arcades. Its philosophy is very much inspired by the Linux kernel (hence the name), which brilliantly manages to support multiple machines while keeping drivers entirely platform-independent. Emux is designed in the same way, keeping a code base of CPUs and controllers separate from machines. ### Author/License The Emux SMS core has been authored by - Sebastien Ronsse The Emux SMS core is licensed under - [GPLv2](https://github.com/libretro/emux/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Emux SMS core have the following file extensions: - .sms - .bin - .rom ## Databases RetroArch database(s) that are associated with the Emux SMS core: - [Sega - Master System - Mark III](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20Master%20System%20-%20Mark%20III.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:--------:|:-----------------------------:|:--------------------------------:| | bios.sms | Master System BIOS - Required | 840481177270d5642a14ca71ee72844c | ## Features Frontend-level settings or features that the Emux SMS core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✕ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✕ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Emux SMS core's internal core name is 'emux (sms)' ### Geometry and timing - The Emux SMS core's core provided FPS is (FPS) - The Emux SMS core's core provided sample rate is (Rate) - The Emux SMS core's core provided aspect ratio is (Ratio) ## Controllers The Emux SMS core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't diable input. There's no reason to switch to this. - **RetroPad** - Joypad - Stay on this. - RetroPad w/Analog - Joypad - There's no reason to switch to this. ### Controller tables #### Joypad ![](../image/controller/sms.png) | RetroPad Inputs | Emux SMS core Inputs | |-------------------------------------------|----------------------| | ![](../image/retropad/retro_b.png) | 1 | | ![](../image/retropad/retro_start.png) | Pause | | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | | ![](../image/retropad/retro_a.png) | 2 | ## External Links - [Official Emux SMS Github Repository](https://github.com/sronsse/emux) - [Libretro Emux SMS Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/emux_sms_libretro.info) - [Libretro Emux SMS Github Repository](https://github.com/libretro/emux) - [Report Libretro Emux SMS Core Issues Here](https://github.com/libretro/libretro-meta/issues) ### See also #### Sega - Master System - Mark III - [Sega - MS/GG/MD/CD (Genesis Plus GX)](genesis_plus_gx.md) - [Sega - MS/MD/CD/32X (PicoDrive)](picodrive.md) ================================================ FILE: docs/library/ep128emu.md ================================================ # Enterprise - 64/128 (ep128emu) ## Background Leverage the convenience of libretro/retroarch to emulate the Z80 based home computers that the original ep128emu supports - that is, Enterprise 64/128, Videoton TVC, Amstrad CPC and ZX Spectrum. Focus is on Enterprise and TVC. The ep128emu core has been authored by: - Istvan Varga (ep128emu) - Zoltan Balogh (libretro core specific modifications) The ep128emu core is licensed under [GPL2](https://github.com/libretro/ep128emu-core/blob/master/COPYING). A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Requirements Since the emulated machines are 8-bit platforms from the 1980's, modern setups should have no problem emulating them. Tested on Raspberry Pi 2. ## Extensions Content that can be loaded by the ep128emu core have the following file extensions: - `.img` - Enterprise, CPC or TVC floppy disk image - `.dsk` - Enterprise, CPC or TVC floppy disk image - `.tap` - Enterprise or ZX Spectrum tape image - `.dtf` - Enterprise compressed file - `.cas` - Videoton TVC file format - `.wav` - sound file interpreted as Enterprise tape - `.tvcwav` - sound file interpreted as Videoton TVC tape - `.cdt` - Amstrad CPC tape image - `.tzx` - ZX Spectrum tape image - `.bas`, `.com`, `.trn`, `.128`, `.` - common extensions for Enterprise executable files, including no extension From version 1.1.0, emulator core is able to handle mono PCM WAV files with 1..8 bit depth as tape recordings. It is possible to enable libsndfile support during compilation, and then a wider range of formats are recognized, including MP3 if libsndfile version is at least 1.1. Using the `.wav` file extension will trigger the built-in RetroArch media player by default, it can be disabled under Settings / File Browser / Use Built-in Media Player. Rename `.wav` files to have `.tvcwav` extension to be interpreted as TVC tapes. RetroArch database(s) that are associated with the ep128emu core: - None yet ## Features Frontend-level settings or features that the ep128emu core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | - | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | - | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✔ | | Username | ✕ | | Language | ✔ | | Crop Overscan | ✕ | | LEDs | ✔ | ## Directories The ep128emu core's library name is `ep128emu`. The ep128emu core saves/loads to/from these directories. **Frontend's System directory** | File | Description | |:------------:|:-----------:| | ep128emu/rom/* |BIOS files are loaded from here | | ep128emu/config/* |System-wide emulation configuration files | ## Geometry and timing - The ep128emu core's core provided FPS is 50 - The ep128emu core's core provided sample rate is 44.1 kHz - The ep128emu core's base width is 768 - The ep128emu core's base height is 288 - The ep128emu core's max width is 768 - The ep128emu core's max height is 576 (interlace mode) - The ep128emu core's core provided aspect ratio is 4:3 (interlace mode) The intelligent zoom function can reduce the apparent width/height, aspect ratio is also adjusted. If there is LED driver configured in RetroArch, second LED should reflect disk activity state. ## Usage Load any supported content file. Content type will be autodetected, and if possible, started. Content-specific [configuration file](https://github.com/libretro/ep128emu-core/blob/core/core/sample.ep128cfg) is also loaded if present. Without content, core starts with Enterprise 128 disk configuration. In case of multi-disk (or multi-tape) games, use the Disk Control menu to add the subsequent images and switch between them. You can also use RetroArch's built-in memory analyzer to set up cheats. Apart from disk/tape/fileIO differences, the core will adjust the emulated machine configuration in some cases: - if content file has `.DTF` extension, ZozoTools BIOS will be used - if content file name contains `[req brd-rom]`, German BIOS will be used - if content file name contains `[req zrom]`, Hungarian language BIOS and EPDOS will be used - if EP128_DISK_ISDOS (or EP64_DISK_ISDOS) type is supplied via configuration file, IS-DOS (CP/M flavor for Enterprise) will be used ## Core options The ep128emu core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - Main thread wait (ms) (**0**|1|5|10) - forced sleep in main thread for lower CPU use - High sound quality (**1**|0) - disable in case of performance problems - Use accelerated SW framebuffer (**0**|1) - enable in case of performance problems (has some known bugs with interlace mode) - Enable resolution changes (requires restart) (**1**|0) - Border lines to keep when zooming in (**0**|2|4|8|10|20) - System ROM version (EP only) (**Original**|Enhanced) - enhanced ROM contains faster memory test at startup - User 1 Zoom button (**R3**|Start|Select|X|Y|A|B|L|R|L2|R2|L3) - User 1 Info button (**L3**|R3|Start|Select|X|Y|A|B|L|R|L2|R2) - User 1 Autofire for button (**None**|X|Y|A|B|L|R|L2|R2|L3|R3|Start|Select) - User 1 Autofire repeat delay (**1**|2|4|8|16) ## Control device types The emulated systems use several joystick types (all digital, with 1 fire button usually). Enterprise and TVC have a built-in joystick, and two external joystick connections. The ep128emu core supports device type changes in the controls menu. Change of the type updates the joypad and fire button mapping. | Emulated machine | User 1 default joypad | User 2 default joypad | User 3 default joypad | |------------------|-----------------------|-----------------------|-----------------------| | Enterprise | Internal | External 1 | External 2 | | TVC | Internal | External 1 | External 2 | | CPC | External 1 | External 2 | | | ZX | Kempston | Sinclair 1 | Sinclair 2 | - Core default - Joypad and fire button is mapped as default (see above) - Internal Joystick - Joypad and fire button is mapped for internal joystick on Enterprise and TVC. On CPC it is mapped to cursor keys. - External Joystick 1 / Kempston - Joypad and fire button is mapped for external joystick 1 (Kempston interface in case of ZX) - External Joystick 2 - Joypad and fire button is mapped for external joystick 2 - Sinclair Joystick 1 - Joypad and fire button is mapped for Sinclair joystick 1. Only useful for ZX. Joystick inputs are emulated as keys: 1 (left), 2 (right), 3 (down), 4 (up), 5 (fire). - Sinclair Joystick 2 - Joypad and fire button is mapped for Sinclair joystick 2. Only useful for ZX. Joystick inputs are emulated as keys: 6 (left), 7 (right), 8 (down), 9 (up) ,0 (fire). - Protek Joystick - Joypad and fire button is mapped for Protek/AGF joystick. Only useful for ZX. Joystick inputs are emulated as keys: 5 (left), 6 (down), 7 (up), 8 (right) ,0 (fire). - External Joystick 3..6 - Joypad and fire button is mapped for external joystick 3..6. Only useful for Enterprise, very rarely used. ## Joypad | RetroPad Inputs | Default action for user 1 | Recommended override
for content-specific configuration | |------------------------------------------------|--------------------------|---------------------------| | ![](../image/retropad/retro_dpad_up.png) ![](../image/retropad/retro_dpad_down.png)
![](../image/retropad/retro_dpad_left.png) ![](../image/retropad/retro_dpad_right.png) | Respective directions for:
Enterprise, TVC: Internal joystick
CPC: External joystick 1
ZX Spectrum: Kempston interface | | | ![](../image/retropad/retro_x.png) | Enterprise, TVC: space (fire for internal joystick)
CPC: External joystick 1 fire
ZX Spectrum: Kempston joystick | | | ![](../image/retropad/retro_y.png) | Enter | | | ![](../image/retropad/retro_a.png) | CPC: External joystick 1 fire 2 | In-game key required for secondary action | | ![](../image/retropad/retro_b.png) | - | In-game key required for other action (if any) | | ![](../image/retropad/retro_select.png) | - | In-game key required to select the supported input method (if any) | | ![](../image/retropad/retro_start.png) | - | In-game key required to start the game (if any) | | ![](../image/retropad/retro_l1.png) | Key 0 | In-game key required for other action (if any) | | ![](../image/retropad/retro_r1.png) | Key 1 | In-game key required for other action (if any) | | ![](../image/retropad/retro_l2.png) | Key 2 | In-game key required for other action (if any) | | ![](../image/retropad/retro_r2.png) | Key 3 | In-game key required for other action (if any) | | ![](../image/retropad/retro_l3.png) | Info display | - | | ![](../image/retropad/retro_r3.png) | Intelligent zoom | (Zoom is also available via keyboard F12) | ## Mouse Mouse input is used for the EnterMice emulation of the Enterprise. ## Keyboard ### Enterprise 128 The ep128emu core takes the Enterprise UK keyboard as a basis: ![](../image/core/ep128emu/enterprise-128-uk-keyboard.png) Most mappings are straightforward positionally from an ISO UK keyboard: - Dark green: natural mapping, both position and function matches nicely - Light green: either position or function is slightly different - Yellow: function is different - Red: extra mapping - Dark grey: keys intentionally reserved for RetroArch / OS functions ![](../image/core/ep128emu/iso-mapping-for-enterprise-128.png) Exceptions are marked in the following table: | RetroKeyboard Inputs | Enterprise keyboard input | |------------------------------|---------------------------| | Keyboard F9 | Hold | | Keyboard F10 | Stop | | Keyboard Pause | Stop | | Keyboard Backquote ` | Escape (alternative mapping) | | Keyboard Equals = | ^ (caret) | | Keyboard Backspace | Erase | | Keyboard Left Bracket [ | @ (at) | | Keyboard Right Bracket ] | [ (left bracket) | | Keyboard Quote ' | : (colon) | | Keyboard Backslash \ | ] (right bracket) (shown as # in ISO map) | | Keyboard Oem 102 | \\ (backslash) | | Keyboard Home | \\ (alternative mapping) | | Keyboard Delete | Del | | Keyboard Insert | Ins | | Keyboard Keypad 0 | External joystick 1 fire | | Keyboard Keypad 2 | External joystick 1 down | | Keyboard Keypad 4 | External joystick 1 left | | Keyboard Keypad 6 | External joystick 1 right | | Keyboard Keypad 8 | External joystick 1 up | ### Videoton TVC The Videoton TVC has a layout that is somewhat similar to ISO Hungarian layout: ![](../image/core/ep128emu/videoton-tvc-keyboard.png) ![](../image/core/ep128emu/iso-mapping-for-videoton-tvc.png) Since TVC has several extra keys, but no function keys, F-row is used as replacement for those. | RetroKeyboard Inputs | TVC keyboard input | |------------------------------|---------------------------| | Keyboard F1 | @ | | Keyboard F2 | ; | | Keyboard F3 | < | | Keyboard F4 | \ | | Keyboard F5 | * | | Keyboard F6 | ^ | | Keyboard F7 | [ | | Keyboard F8 | ] | | Keyboard F9 | * | | Keyboard F10 | í | | Keyboard Backquote ` | 0 | | Keyboard 0 | ö | | Keyboard Minus - | ü | | Keyboard Equals = | ó | | Keyboard Left Bracket [ | ő | | Keyboard Right Bracket ] | ú | | Keyboard Semicolon ; | é | | Keyboard Quote ' | á | | Keyboard Backslash \ | ű | | Keyboard Oem 102 | í | | Keyboard Home | ű (alternative mapping) | | Keyboard Delete | Del | | Keyboard Insert | Ins | | Keyboard Keypad 0 | External joystick 1 fire | | Keyboard Keypad 2 | External joystick 1 down | | Keyboard Keypad 4 | External joystick 1 left | | Keyboard Keypad 6 | External joystick 1 right | | Keyboard Keypad 8 | External joystick 1 up | ### Amstrad CPC The Amstrad CPC 464/664 and 6128 fit well to ISO UK layout, with only slight differences: ![](../image/core/ep128emu/amstrad-cpc-464-keyboard.png) ![](../image/core/ep128emu/amstrad-cpc-6128-keyboard.png) ![](../image/core/ep128emu/iso-mapping-for-amstrad-cpc.png) Function key row is mapped to Fn-array. Extra mappings are marked in the following table: | RetroKeyboard Inputs | CPC keyboard input | |------------------------------|---------------------------| | Keyboard F1 | Fn1 | | Keyboard F2 | Fn2 | | Keyboard F3 | Fn3 | | Keyboard F4 | Fn4 | | Keyboard F5 | Fn5 | | Keyboard F6 | Fn6 | | Keyboard F7 | Fn7 | | Keyboard F8 | Fn8 | | Keyboard F9 | Fn9 | | Keyboard F10 | Fn0 | | Keyboard F11 | Fn Dot (.) | | Keyboard Keypad Enter | Fn Enter | | Keyboard Oem 102 | \\ | | Keyboard Home | \\ (alternative mapping) | | Keyboard Delete | Del | | Keyboard Insert | Copy | | Keyboard Left Alt | Copy (alternative mapping) | | Keyboard Right Alt | Fn Dot (alternative mapping) | | Keyboard Keypad 0 | External joystick 1 fire | | Keyboard Keypad Period . | External joystick 1 fire 2 | | Keyboard Keypad 2 | External joystick 1 down | | Keyboard Keypad 4 | External joystick 1 left | | Keyboard Keypad 6 | External joystick 1 right | | Keyboard Keypad 8 | External joystick 1 up | ## BIOS Following "BIOS" files are used for emulation. Note: in usual 8-bit home computer terms, these are "ROM"s as they contain the original machine's read-only memory dumps. From ep128emu_core version 1.1.0, external BIOS files are optional. | Filename | Description | md5sum | |:-----------------:|:-------------------------------:|:--------------------------------:| | `exos21.rom` | Enterprise 128 Expandible OS 2.1
For EP128 | f36f24cbb87745fbd2714e4df881db09 | | `basic21.rom` | Enterprise 128 BASIC Interpreter v2.1
For EP128 | e972fe42b398c9ff1d93ff014786aec6 | | `exdos13.rom` | Enterprise 128 Disk Controller v1.3
For EP64/128 disk configs | ddff70c014d1958dc75378b6c9aab6f8 | | `exos20.rom` | Enterprise 64 Expandible OS 2.0
For EP64 | 5ad3baaad3b5156d6b60b34229a676fb | | `basic20.rom` | Enterprise 64 BASIC Interpreter v2.0
For EP64 | 8e18edce4a7acb2c33cc0ab18f988482 | | `epfileio.rom` | Enterprise 128 Direct File I/O
For loading from host file (instead of disk or tape image) | a68ebcbc73a4d2178d755b7755bf18fe | | `exos24uk.rom` | Enterprise 128 Expandible OS 2.4
Only for enhanced functions (fast memory test) | 55af78f877a21ca45eb2df68a74fcc60 | | `hun.rom` | Enterprise 128 Hungarian language extension | 22167938f142c222f40992839aa21a06 | | `epdos16f.rom` | Enterprise 128 EP-DOS | 6593dff00ab32a4b1fc084674ededf2b | | `exdos14isdos10uk.rom` | Enterprise 128 IS-DOS (CP/M) | f91c4a507cc6895bdd9c43df4f021df3 | | `brd.rom` | Enterprise 128 German language extension | 6af0402906944fd134004b85097c8524 | | `zt19uk.rom` | Enterprise 128 ZozoTools extension
For loading from DTF files | 228540b6be83ae2acd7569c8ff0f91d0 | | `tvc22_sys.rom` | Videoton TVC system BIOS
For TVC emulation | 8c54285f541930cde766069942bad0f2 | | `tvc22_ext.rom` | Videoton TVC extension BIOS
For TVC emulation | 5ce95a26ceed5bec73995d83568da9cf | | `tvcfileio.rom` | Videoton TVC Direct File I/O
For loading from host file (instead of disk or tape image) | a2cf86ba8e7fc58b242137fe59036832 | | `tvc_dos12d.rom` | Videoton TVC disk BIOS
For TVC disk configs | 88dc7876d584f90e4106f91444ab23b7 | | `cpc464.rom` | Amstrad CPC 464 BIOS
For CPC 464 | a993f85b88ac4350cf4d41554e87fe4f | | `cpc664.rom` | Amstrad CPC 664 BIOS
For CPC 664 | 5a384a2310f472c7857888371c00ed66 | | `cpc6128.rom` | Amstrad CPC 6128 BIOS
For CPC 6128 | b96280dc6c95a48857b4b8eb931533ae | | `cpc_amsdos.rom` | Amstrad CPC AMSDOS BIOS
For CPC disk configs | 25629dfe870d097469c217b95fdc1c95 | | `zx128.rom` | ZX Spectrum 128 BIOS
For ZX Spectrum 128 | 85fede415f4294cc777517d7eada482e | | `zx48.rom` | ZX Spectrum 48 BIOS
For ZX Spectrum 16/48 | 4c42a2f075212361c3117015b107ff68 | ## Special emulation Enterprise 128 has software extensions to emulate ZX Spectrum (48, 128) and Amstrad CPC. As a technical quirk, these emulators can be run in the ep128emu-core, creating a double emulation layer. ### SPEMU - Obtain ROM version of SPEmu from the [EnterpriseForever forums](https://enterpriseforever.com/letoltesek-downloads/enterprise-software/). - Place ROM files under RetroArch system directory: `system/ep128emu/roms/` - Create a custom config file next to the content (such as a .tzx file) called `enterprise.ep128cfg`: `machineDetailedType "EP128_TAPE"` `memory.ram.size 256` `memory.rom.40.file "spemu128.rom"` `memory.rom.40.offset 0` `memory.rom.41.file "spemu128.rom"` `memory.rom.41.offset 16384` `memory.rom.42.file "spemu128.rom"` `memory.rom.42.offset 32768` `tape.forceMotorOn Yes` - Start ep128emu core using the tape content - Invoke the SPEmu extension with `:sp128` - Choose Load tape ### CPCEMU - Obtain COM version of CPCEmu from the [EnterpriseForever forums](https://enterpriseforever.com/letoltesek-downloads/enterprise-software/). - Start CPCEMU.COM the usual way (select the file in RetroArch and open it with ep128emu core) - Once the blue screen has loaded, open quick menu (F1) go to Disk Control and select the file that needs to be loaded - Continue, enable keyboard pass-through with Scroll Lock, and issue RUN command as needed - It may be needed to change the control type to External 2 in Quick Menu / Controls ## External Links - [Official ep128emu-core Repository](https://github.com/libretro/ep128emu-core) - [Libretro ep128emu Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/ep128emu_core_libretro.info) - [Report Libretro ep128emu Core Issues Here](https://github.com/libretro/ep128emu-core/issues) - [Original ep128emu Implementation](https://github.com/istvan-v/ep128emu) - [ep128.hu](http://www.ep128.hu/) - games for Enterprise - [enterpriseforever.com](https://enterpriseforever.com/) - Enterprise community - [tvc.homeserver.hu](http://tvc.homeserver.hu/) - TVC page (Hungarian only) ================================================ FILE: docs/library/fbneo.md ================================================ # FinalBurn Neo ## Note about this document It mostly assumes you are using RetroArch as your libretro frontend, some specific instructions might differ if you are using another frontend. It also assumes you are already knowledgeable about arcade emulation and its quirks. If you aren't, you should be reading [getting started with arcade emulation](https://docs.libretro.com/guides/arcade-getting-started/) first. ## Background FinalBurn Neo (also referred to as FBNeo or FBN) is a multi-system emulator (Arcade, consoles and computers) under active development. It is the follow-up of the FinalBurn and FinalBurn Alpha emulators. The libretro core provides wide compatibility with platforms and features supported by libretro. ## Difference from MAME FBNeo strives for accuracy, just like MAME. There are some arcade boards where one or the other will be more accurate, but for the most part they should be equally accurate. The main difference with MAME is that FBNeo doesn't mind including "quality of life" hacks, while MAME is mostly focused on preservation and documentation. "Quality of life" hacks include things like : * improving original game's sound (some games like "Burger Time" have noise which was clearly unintended by their developpers, we are removing it) * implementing alternative colors for games where the colors don't look right (sometimes there are controversies about which colors are right for an arcade board, like "Tropical Angel", we implement alternative colors as dipswitches) * having control alternatives that didn't exist on original cabinet (play rotary stick games like twin-stick shooters, use lightguns in "Rambo 3", use simplified 8-way directional controls for "Battlezone", ...) * improving the gaming experience by cutting what we deem as unnecessary aspect of emulation (you don't have to spend 20 minutes "installing" CPS-3 games, neither 100s loading Deco Cassette games) * reducing hardware requirements by cutting what we deem as unnecessary corners in the emulation code * supporting popular romhacks Note: some of those "quality of life" hacks might be doable with programming skills and lua language on MAME ## License and changelog It's distributed under a non-commercial license, see [LICENSE.md](https://github.com/finalburnneo/FBNeo/blob/master/LICENSE.md) and [whatsnew.html](https://github.com/finalburnneo/FBNeo/blob/master/whatsnew.html). There are controversies about whether libretro's patreon and retroarch's GPL license breaks FBNeo's non-commercial license or not. This is what you should know : * **"Redistributions may not be sold, nor may they be used in a commercial product or activity."** : By definition, a commercial activity is an activity involving the sale of goods or services. The libretro project does none of that, and it is unclear whether a patreon should be treated as a commercial activity or not when no goods or services are provided in exchange of the donations. * **"You may not ask for donations to support your work on any project that uses the FB Neo source code."** : This FBNeo port is using libretro code, not the other way around. This port is directly authored/maintained/supported by members of the FBNeo team, and none of them is receiving donations. Interestingly, if receiving donations was de facto a commercial activity, this term shouldn't be required. * *If* the libretro project was a commercial activity, it would still be unclear how it does affect this port. Our win32 standalone builds use the directx api, which belongs to a commercial company. Using the libretro api, which would belong to a commercial activity, wouldn't be any different. Furthermore, in all likeliness, there would still be alternative libretro frontends that don't belong to the libretro project and are not commercial. * Actually, alternative commercial libretro frontends already exist, and we consider we are not concerned as long as they neither redistribute FBNeo nor use it as some mean of advertisement. In this scenario, only a manual installation of the core by the user will be considered legal and supported. * While GPL code can't be mixed with non-commercial code, this is a non-issue since this port doesn't contain any GPL-licensed code. * Under european law, where the libretro buildbots are located, linking GPL and non-commercial softwares doesn't produce a derivative work, and doesn't extend the GPL license to the non-commercial work (source [here](https://joinup.ec.europa.eu/collection/eupl/licence-compatibility-permissivity-reciprocity-and-interoperability)). It is unclear whether the same applies in non-EU countries or not. ## Extensions zip, 7z ## Building this core manually From the root of the repository, run ``` make -j5 -C src/burner/libretro ``` Note : `-j5` is to optimize build time on cpus with 4 cores (X+1 cores), you can rise or reduce that value to match your own, however a value too high will increase ram usage and might even cause your system to become unstable. Note : Here is a non-exhaustive list of additional parameters you might want to append to the make command line : * **SUBSET=all** : Build a core that supports everything. This is the default SUBSET so you don't need to append it. * **SUBSET=neogeo** : Build a core that only supports neogeo games. * **SUBSET=cps12** : Build a core that only supports CPS-1 & CPS-2 games. * **generate-files** : Generate header/gamelist files and stop there. * **clean** : Remove any previously built object. * **REGEN_HEADERS=1** : This will run **generate-files** and **clean** consecutively before building the core, which is usually required when you made a change to the list of drivers you want to build, either from modifying the project's code or switching between SUBSETs. Note that make version 4.4 may be required for this to behave properly. ## Building romsets for FBNeo You won't be able to emulate games without the romsets matching this emulator. FBNeo being an emulator under active development, a given romset might change from time to time to stay in sync with the best dump available for that game. Don't expect things to work properly if you didn't build valid romsets, and don't report issues because your romsets are invalid. ### Step 1: Obtaining an XML DAT You can download the dat files for the latest version of the core from the [dats](https://github.com/libretro/FBNeo/tree/master/dats/) directory. ### Step 2: Gathering the ingredients It mostly consists of latest dumps available for MAME. The other romsets are usually a mix of hacks and homebrews, most of them can be found in HBMAME dumps. Console/computer romsets come from different sources (recently emulated systems are likely to be based on No-Intro, but older ones were mostly based on MESS, there are also a lot of hacks/homebrews you won't find in those sets). Having an older FBAlpha/FBNeo set among your ingredients will also help a lot. ### Step 3: Building the romsets Refer to a [clrmamepro tutorial](https://docs.libretro.com/guides/arcade-getting-started/#optional-clrmamepro-tutorial) for details on how to configure ClrMamePro to use your sources as "rebuild" folders. ## Features | Feature | Supported | |-------------------------------------------------------------------|-----------| | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Run-Ahead | ✔ | | Preemptive Frames | ✔ | | Netplay | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✔ | | Controllers | ✔ | | Multi-Mouse | ✔ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✔ | | IPS Patch | ✔ | | RomData | ✔ | | Multi-language | ✔ | ## Mapping We don't have a tool like the MAME OSD, instead we use the libretro api to announce buttons and let the frontend customize mapping, this is done through `Quick Menu > Controls`. For those who don't want to fully customize their mapping, there are 2 convenient presets you can apply by changing the "device type" for a player in this menu : * **Classic** : it will apply the original neogeo layout from neogeo cd gamepads for neogeo games, and use L/R as 5th and 6th button for 6 buttons games like Street Fighter II. * **Modern** : it will apply the modern neogeo layout from neogeo arcade stick pro and mini pad for neogeo games, and use R1/R2 as 5th and 6th button for 6 buttons games like Street Fighter II (because it's also their modern layout), this is really convenient with most arcade sticks. The following "device type" also exist, but they won't be compatible with every games : * **Mouse (ball only)** : it will use mouse/trackball for analog movements, buttons will stay on retropad * **Mouse (full)** : same as above, but the buttons will be on the mouse * **Pointer** : it will use "pointer" device (can be a mouse/trackball) to determine coordinates on screen, buttons will stay on retropad * **Lightgun** : it will use lightgun to determine coordinates on screen, buttons will be on the lightgun too. * **Analog Arcade Gun** : it will use the analog stick for gun games but in a different way than "Classic" and "Modern", it is particularily useful if you have a "fixed arcade gun" (arcade gun mounted on an analog control). The following device types are mostly WIP, they haven't been thoroughly tested and might contain major bugs (please report them) : * **6-Panel** : assuming you are using a 6-button arcade panel and followed the "YXL as top row and BAR as bottom row" mapping recommendation, it will map the top row then the bottom row as a general rule (with some exceptions), note that some users might be more comfortable with Classic/Modern's BAYX's assignment for 4-buttons systems like neogeo. * **Touchscreen** : a variant of the "Pointer" device type meant for mobile devices, touchscreen "tap events" are used for gameplay, "Start" and "Coin" are still assigned to your retropad overlay. ## Emulating consoles and computers It also requires usage of specific romsets, meaning the rom must have the expected crc/size, and be packaged in an archive with a specific name ([the instructions to build those romsets aren't different from arcade](#building-romsets-for-fbneo)). You can use specific folder's name for detection, it's the easiest and recommended method, especially if you are using RetroArch playlists or if your device is not compatible with subsystems (android and consoles) : * CBS ColecoVision : `coleco` | `colecovision` * Fairchild ChannelF : `chf` | `channelf` * MSX 1 : `msx` | `msx1` * Nec PC-Engine : `pce` | `pcengine` * Nec SuperGrafX : `sgx` | `supergrafx` * Nec TurboGrafx-16 : `tg16` * Nintendo Entertainment System : `nes` * Nintendo Family Disk System : `fds` * Super Nintendo Entertainment System : `snes` * Sega GameGear : `gamegear` * Sega Master System : `sms` | `mastersystem` * Sega Megadrive : `megadriv` | `megadrive` | `genesis` * Sega SG-1000 : `sg1000` * SNK Neo-Geo Pocket : `ngp` * SNK Neo-Geo CD : `neocd` * ZX Spectrum : `spectrum` | `zxspectrum` You can also emulate consoles by prefixing the name of the roms with `XXX_` and removing the `zip|7z` extension in the command line, or adding the `--subsystem XXX` argument, here is the list of available prefixes : * CBS ColecoVision : `cv` * Fairchild ChannelF : `chf` * MSX 1 : `msx` * Nec PC-Engine : `pce` * Nec SuperGrafX : `sgx` * Nec TurboGrafx-16 : `tg` * Nintendo Entertainment System : `nes` * Nintendo Family Disk System : `fds` * Super Nintendo Entertainment System : `snes` * Sega GameGear : `gg` * Sega Master System : `sms` * Sega Megadrive : `md` * Sega SG-1000 : `sg1k` * SNK Neo-Geo Pocket : `ngp` * SNK Neo-Geo CD : `neocd` * ZX Spectrum : `spec` ## BIOS When loading a romset requiring a bios romset, it will be searched through 3 folders in that order : * the folder of the current romset * the `SYSTEM_DIRECTORY/fbneo/` folder * the `SYSTEM_DIRECTORY/` folder The following bios romsets are required for some of the emulated arcade systems : | Romset name | Note | |-------------|--------------------------------------------| | bubsys | Bubble System BIOS | | cchip | C-Chip Internal ROM | | decocass | DECO Cassette System BIOS | | isgsm | ISG Selection Master Type 2006 System BIOS | | midssio | Midway SSIO Sound Board Internal ROM | | msx | MSX1 System BIOS | | namcoc69 | Namco C69 BIOS | | namcoc70 | Namco C70 BIOS | | namcoc75 | Namco C75 BIOS | | neogeo | Neo Geo BIOS | | nmk004 | NMK004 Internal ROM | | pgm | PGM System BIOS | | skns | Super Kaneko Nova System BIOS | | ym2608 | YM2608 Internal ROM | The following bios romsets are required for some of the emulated non-arcade systems : | Romset name | Note | |-------------|--------------------------| | channelf | Fairchild Channel F BIOS | | coleco | ColecoVision System BIOS | | dsp1 | SNES DSP-1 | | dsp1b | SNES DSP-1B | | dsp2 | SNES DSP-2 | | dsp3 | SNES DSP-3 | | dsp4 | SNES DSP-4 | | fdsbios | FDS System BIOS | | neocdz | Neo Geo CDZ System BIOS | | ngp | NeoGeo Pocket BIOS | | spectrum | ZX Spectrum BIOS | | spec128 | ZX Spectrum 128 BIOS | | spec1282a | ZX Spectrum 128 +2a BIOS | | st010 | SNES Seta ST010 | | st011 | SNES Seta ST011 | ## Samples Samples should be put under `SYSTEM_DIRECTORY/fbneo/samples`. Here is a list of samples currently in use : | Sample name | Note | |--------------|------------------------------------------------------------------------| | ad59mc07 | Known as `equites` in MAME | | blockade | | | buckrog | | | carnival | | | cheekyms | Not from MAME | | circus | | | crash | | | congo | | | deathnlead | Not from MAME, megadrive | | depthch | | | digger | Not from MAME | | dkongjr | | | dkong | | | donpachi | Not from MAME, optional, replace OG music by HQ music, requires dipsw. | | elim2 | | | fantasy | | | galaga | | | gaplus | | | gridlee | | | heiankyo | Not from MAME | | invaders | | | invds | Not from MAME | | invinco | | | journey | | | mario | | | mmagic | | | natodef | | | nitedrvr | Not from MAME | | nsub | | | paprium | Not from MAME, megadrive, huge usage of disk space and ram (2.1GB) | | qbert | | | radarscp | Not from MAME | | rallyx | | | reactor | | | safarir | | | sasuke | | | seawolf | | | sfz3mix | Not from MAME, optional, replace OG music by HQ music, no dipsw. | | sharkatt | | | sidetrac | Not from MAME | | sot4w | Not from MAME, megadrive | | spacefb | | | spacfury | | | stinger | Not from MAME | | subroc3d | | | targ | | | thehand | | | thief | | | tr606drumkit | Not from MAME | | turbo | | | twotiger | | | vanguard | | | xevious | | | zaxxon | | | zektor | | | zerohour | | ## Hiscores Copy [hiscore.dat](https://github.com/libretro/FBNeo/raw/master/metadata/hiscore.dat) to `SYSTEM_DIRECTORY/fbneo/` and have `Quick Menu > Core Options > Hiscores` enabled. It doesn't guarantee hiscores will work for a specific game though, sometimes a driver could just be missing the necessary support code for this feature, or `hiscore.dat` might have a missing or broken entry for that romset. You can request support in the issue tracker. Runahead now works with hiscores, it'll require fairly recent version of the core AND RetroArch though (support was added after 1.10.3). ## Input lag reduction This core widely supports the RetroArch input latency reduction features, with **runahead single instance** and **preemptive frames** being the recommended methods. Proper support for **runahead second instance** is not guaranteed because it doesn't exist in standalone FBNeo unlike the other methods. Note : There seems to be possible conflicts when rewind is active simultaneously, see https://github.com/libretro/RetroArch/issues/16374. ## RetroAchievements This core provides support for RetroAchievements, and some were added for popular games. ## Dipswitches They are either directly available from `Quick Menu > Core Options > DIP Switches`, or from the service menu after setting its shortcut at `Quick Menu > Core Options > Diagnostic Input`. ## Cheats This core supports the RetroArch cheat feature with the `.cht` files. However it is recommended to use FBNeo's native cheat support instead : * Download the pack of cheats from [here](https://github.com/finalburnneo/FBNeo-cheats/archive/master.zip) * Uncompress **all of them** into the `SYSTEM_DIRECTORY/fbneo/cheats/` folder (which is **NOT** the same folder as the RetroArch feature with the `.cht` files) * Cheats will become available through core options (`Quick Menu > Core Options > Cheat`, **NOT** `Quick Menu > Cheats`) afterward. ## Multi-language This core supports multi-language feature. * Multi-language is based on the front-end User UI language switching * Simplified Chinese and Traditional Chinese have been added. ## Frequently asked questions ### Where can i find the XXX roms ? As far as we are concerned, you are supposed to dump your own games, so we can't help you with acquiring romsets. ### Why am i getting a white screen ? If present, the line `Verify the following romsets : ` gives you the list of split romsets required by the game you are trying to run. This is mainly for reference since you might not be striving to use romsets in split format. The next few lines give you the list of files it couldn't find within those romsets. Otherwise, a `Romset is unknown` message means the romset couldn't be found by its filename in our database, meaning it's either not supported at all or wrongly named. Both problems result from not reading the [arcade documentation](https://docs.libretro.com/guides/arcade-getting-started/#step-3-use-the-correct-version-romsets-for-that-emulator). Exceptionally there might be false positives due to your files being unreadable for some reason (file corruption during transfer, file permission, damaged disk drive, [retroarch regression](https://github.com/libretro/RetroArch/issues/18582), ...). This is usually a rabbit hole and something you should only concern yourself after using clrmamepro to verify your romsets. Rarely you could get a "Failed initializing driver" message, this is something you should report [here](https://github.com/finalburnneo/FBNeo/issues) ### Is XXX supported ? You can check the [dats](https://github.com/libretro/FBNeo/tree/master/dats/) or [gamelist.txt](https://raw.githubusercontent.com/libretro/FBNeo/refs/heads/master/gamelist.txt) to see if a game is supported. We don't accept requests for supporting a game, and questions regarding the lack of support for a game are also regarded as requesting for its support. One exception to that rule would be for consoles/computers we already support, and you should make that request [here](https://neo-source.com/index.php?topic=3656.0). Games running on already emulated arcade systems will also be tolerated, the most common case for this would be romhacks of already emulated games, don't ask if you are not absolutely sure. ### How can i run that romhack i found ? A lot of romhacks are supported natively, so your romhack might already be supported under a specific romset name. For the unsupported romhacks, there are 3 methods, but those romhacks are not allowed if you intend to use RetroAchievements and must be disabled by toggling off `Quick Menu > Core Options > Allow patched romsets` : #### Using the "patched" folder * Put the patched version of the romset into `SYSTEM_DIRECTORY/fbneo/patched`, this folder has special privileges allowing it to ignore crcs. Sizes and names still need to match the original romset though. * Optional : you could strip the patched version from any file that don't differ from the original romset. #### Using IPS Patches * Put all IPS patch files (including: driver name directory/**.dat|**.ips) into the `SYSTEM_DIRECTORY/fbneo/ips/` folder. * IPS Patch will become available through core options (`Quick Menu > Core Options > IPS Patch`) afterward. To apply them, you need to launch the game, enable them in core options, then use RetroArch's "restart" action. * Note : To avoid competing with loaded games for startup privileges, IPS Patches is initially disabled by default. #### Using RomData * Put all RomData files (including: driver name directory/**.dat) into the `SYSTEM_DIRECTORY/fbneo/romdata/` folder * RomData will become available through core options (`Quick Menu > Core Options > RomData`) afterward. To apply them, you need to launch the game, enable them in core options, then use RetroArch's "restart" action. Please note that all 3 methods still require that you launch the original non-patched romset, it will be patched/replaced at runtime. ### How can i run that unibios i bought from http://unibios.free.fr/ ? Use the "patched folder" method from above. ### I think i found a glitch, how do i report it ? Write a report [here](https://github.com/finalburnneo/FBNeo/issues) with details on the issue and your platform. If the issue is not self-explanatory, it is important to provide a video of the PCB (meaning real hardware), any other material (remakes, other emulators, fpga, game rips, ...) will be ignored. If the issue doesn't happen right from the beginning, please try to provide a savestate from right before the issue. ### Why does game XXX run slowly ? Your hardware is probably too slow to run the game with your current settings. Try the following : * Check if there is a speedhack dipswitch in the core options, set it to "yes". * Try disabling rewind, runahead, pre-emptive frames, shaders, or any other retroarch setting known for increasing requirements. * Try enabling "Threaded Video" in retroarch settings. * Try changing "Max swapchain images" in retroarch settings (higher values gave a small performance benefit on my setup). * Try setting a value for frameskip in core options (note : "Fixed" frameskip is recommended, the other methods don't seem to be nearly as reliable). * Try lowering CPU clock in core options (note : some games don't support this feature). * Try lowering audio settings in the core options. * With m68k games (most boards from the late 80s and early 90s) on arm platforms, you can try enabling cyclone in core options, however this is really a last resort since some games won't work properly with this, furthermore it's causing savestates incompatibilities. * If it is not enough, upgrade/overclock your hardware, or use another core. We won't accept requests for "making the core faster", as far as we are concerned this core has a good balance between accuracy & speed, and for the most part will already run really well on low-end devices (rpi3, ...). ### Why does game XXX have choppy sound ? Most likely for the same reason as above. ### Why does game XXX run faster in MAME2003/MAME2010 ? Overall, FBNeo is slower than old MAME version, because it's more accurate, meaning graphics, sound and gameplay are more likely to be faithful to the real machine. This libretro port also supports various features which are usually buggy or totally missing in MAME cores (runahead, netplay, rewind, retroachievements, ...), those features might require additional resources. ### How do i launch a neogeo CD game ? There are several things to know : * You need to follow the instructions about [emulating consoles](#emulating-consoles-and-computers) * You need a copy of the `neocdz.zip` and `neogeo.zip` bioses * The supported format is single file MODE1/2352 cue/bin (the format where there is one .cue file with one single .bin file). Use "CDmage" to convert your dump if needed. **It must not be compressed** You can convert your unsupported dumps by following this tutorial : * Get [CDMage 1.02.1 (beta)](https://www.videohelp.com/software/CDMage) (freeware & no ads). **Don't get CDMage 1.01.5, it doesn't have the "Save As" function** * File > Open > select your dump (NB : always choose the .cue file if there is one) * File > Save As > write the name of your new file * Make sure you select MODE1/2352 in the second drop-down * Press OK, wait for the process to finish (a few seconds on my computer), and it’s done ! ### Why can't i launch Killer instinct ? I heard it's supported. That driver was disabled, it didn't meet our quality criteria. There are no plans for fixing it at the moment. ### Where is the hires dipswitch on vector games ? It seems gone. It was streamlined into a global `Video Settings > Resolution` core option affecting all vector games at once, with new resolutions available. For best visual results, it's recommended to match your screen's height, some examples using a 1080p screen : * for horizontal games, you'll want to use 1440x1080 * for vertical games (tempest, tacscan), if you are running them on a vertical screen with the settings to rotate them, you'll also want to use 1440x1080 * for those same vertical games, if you are running them at default settings on a horizontal screen, you'll want to use 1080x810 ### Why are vertical games not working properly ? 2 settings are required when running vertical games in FBNeo : * `Settings > Core > Allow rotation` must be enabled (`video_allow_rotate = "true"` in `retroarch.cfg`) * `Settings > Video > Scaling > Aspect Ratio` should be set to `Core Provided` (`aspect_ratio_index = "22"` in `retroarch.cfg`) If you are wondering why this isn't required for the MAME core, you can find more information about it [here](https://github.com/libretro/mame/issues/261) Additionally : * If you are playing on a vertical screen, you'll want to use the `Video Settings > Vertical Mode` core option to rotate the display for your needs, it should also be possible to rotate display from `Settings > Video > Output > Video Rotation` but that method might handle the aspect ratio incorrectly. * If you are using a bezel pack, make sure it's compatible with FBNeo (apparently, some were written specifically to work with MAME's internal rotation) and to follow its official instructions. In some case it seems enabling `Settings > On-Screen Display > On-Screen Overlay > Auto-Scale Overlay` (`input_overlay_auto_scale = "true"` in `retroarch.cfg`) can help. ### Why is the music high-pitched, too fast and/or different from what i think it should be ? The first question you should be asking yourself is "what am i comparing this to ?", emulation is meant to be faithful to real hardware (here the original arcade board), not to some console port, remaster, other emulator, or ost. If you are comparing this to FBNeo standalone, you must be warned that the libretro port is using different default audio settings. By default standalone has 44100 samplerate and both interpolations off, and that's what you should set in core options if you want the same audio output. Last but not least, you might also want to make sure you are running the game at the correct speed, most crt games don't run at 60Hz and if you want the proper refresh rate to be emulated you'll need to make sure `Video Settings > Force 60Hz` isn't enabled in core options and `Settings > Video > Synchronization > Sync to Exact Content Framerate` is enabled (`vrr_runloop_enable = "true"` in `retroarch.cfg`). Please note that it'll likely cause frame duping if your hardware is not compatible with VRR (Variable Refresh Rate), in which case you'll have to make a choice between animation smoothness and correct refresh rate. ### Why do i get a black screen and/or can't i change bios in neogeo games ? The `neogeo` romset is a collection of neogeo bioses, and most of them are considered optional so they won't cause a "white screen" when missing. Only `MVS Asia/Europe ver. 6 (1 slot)` is mandatory. However, having an incomplete romset can still cause various issues : * If you are using the "Use bios set in BIOS dipswitch" as "Neo-Geo mode" and the bios set in dipswitches is missing, you'll have a black screen where you can hear some sound playing. * If you are using any of the other choices available in "Neo-Geo mode" and a corresponding bios can't be found, the core will fallback to one of the available bioses. Obviously, none of this is supposed to ever happen if you followed the instructions about romsets as you are supposed to. ### Why do i get some weird transparent effects in game XXX ? You probably installed some `.bld` files in the `SYSTEM_DIRECTORY/fbneo/blend` folder. Those files are meant to create such effects but some of them are very broken. I'd recommend removing them. ### Why is my favorite combo button not available ? Libretro doesn't allow cores to declare more buttons and map them later, meaning the number of different "actions" available is limited by the number of buttons available on the retropad model. Removing that limitation was asked in https://github.com/libretro/RetroArch/issues/6718, then again in https://github.com/libretro/RetroArch/issues/11273, it's not possible to add more macros as long as this limitation exists. If you want more macros, go support those issues, preferably the later. The currently available neogeo combos were decided in https://github.com/libretro/FBNeo/issues/51, they won't be replaced, but they might totally disappear if users keep complaining about them. Note that there was also a request to add a retroarch macro mapper in https://github.com/libretro/RetroArch/issues/8209. There is also a PR currently opened to implement this : https://github.com/libretro/RetroArch/pull/16035. ### Why can't i enable hardcore mode in RetroAchievements ? This feature doesn't accept achievements made with any kind of cheat, meaning unibios, cheats, and patched romsets must be disabled in core options. ### Why do i need to re-enable cheats every time i boot a game ? It is common for arcade machines to execute self-tests at boot, and in many cases they won't boot if unexpected values have been injected into their memory, which is exactly what cheats do. Disabling cheats at boot is a safety mecanism to prevent those boot issues. ### Why do the self-tests at boot fail ? Sometimes the NVRAM/EEPROM saved on your disk gets corrupted for some reason, Konami games are especially known for getting this issue *somewhat frequently*. NVRAM/EEPROM are saved in the `SAVEFILES_DIRECTORY/fbneo` folder, and you can get around this issue by finding the files corresponding to your game and deleting them. ### Should i use retroarch's analog-to-digital feature ? You should **NEVER** use that feature with this core, it already converts analog to digital and digital to analog internally. Exceptionally it might not do that conversion because each of those controls are already doing their own thing, meaning you don't want that conversion either. ### Why is my old savestate not working anymore after updating my core ? A core's savestates are only guaranteed to keep working as long as you NEVER update that core. Savestates are tied to how a game is emulated, and updating a core might significantly change how that game is emulated, breaking older savestates in the process. This does apply to any core, but is likely to be more frequent for actively developed multi-system emulators like FBNeo. You should be wary of updating your cores if this is a major concern for you. Note that rollback netplay with mismatching core versions can also be affected by this. ### Why am i having trouble playing with a keyboard ? Keyboards, especially cheaper ones, are often affected by ghosting, which will prevent some key combinations from working and hinder your experience. You can test your keyboard [here](https://www.microsoft.com/applied-sciences/projects/anti-ghosting-demo). Additionally, keyboards are kind of unsuitable for arcade emulation, because they allow things that were impossible on real hardware, like pressing opposite directions. This commonly leads to problems while doing special moves involving opposite directions in fighting games. The FBNeo core has a core option at `Input Settings > SOCD Mode` to mitigate this, and some value might work better than another for your play style. ### Where is SYSTEM_DIRECTORY ? Open your `retroarch.cfg` file and look for `system_directory`, or check `Settings > Directory > System/BIOS`. ## External Links - [Official FBNeo forum](https://neo-source.com/) - [Official FBNeo github repository](https://github.com/finalburnneo/FBNeo) - [Libretro FBNeo github repository](https://github.com/libretro/FBNeo) - [[GUIDE] Setting up RetroArch playlists with FBNeo](https://neo-source.com/index.php?topic=3725.0) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0IfsAHeGqGD-DkRzI87q7V_Q) ================================================ FILE: docs/library/fceumm.md ================================================ # Nintendo - NES / Famicom (FCEUmm) ## Background FCEU "mappers modified" is an unofficial build of FCEU Ultra by CaH4e3, which supports a lot of new mappers including some obscure mappers such as one for unlicensed NES ROM's. ### Author/License The FCEUmm core has been authored by - FCEU Team - CaH4e3 The FCEUmm core is licensed under - [GPLv2](https://github.com/libretro/libretro-fceumm/blob/master/Copying) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the FCEUmm core have the following file extensions: - .fds - .nes - .unif - .unf ## Databases RetroArch database(s) that are associated with the FCEUmm core: - [Nintendo - Nintendo Entertainment System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%20Entertainment%20System.rdb) - [Nintendo - Family Computer Disk System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Family%20Computer%20Disk%20System.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:-------------:|:----------------------------------------------------------------------------------------------------------------------------:|:--------------------------------:| | disksys.rom | Family Computer Disk System BIOS - Required for Famicom Disk System emulation | ca30b50f880eb660a320674ed365ef7a | |gamegenie.nes | Game Genie add-on cartridge - Required for Game Genei Add-on emulation | 7f98d77d7a094ad7d069b74bd553ec98 | ## Features Frontend-level settings or features that the FCEUmm core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✔ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The FCEUmm core's internal core name is 'FCEUmm' The FCEUmm core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:----------------------:| | *.srm | Cartridge battery save | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | **Frontend's System directory** | File | Description | |:--------:|:----------------------------:| | nes.pal | Custom palette (64 triplets) | ### Geometry and timing - The FCEUmm core's core provided FPS is NTSC 60.10, PAL/Dendy 50.0 - The FCEUmm core's core provided sample rate is 48000 Hz - The FCEUmm core's base width is 256 (602 when using NTSC Filters) - The FCEUmm core's base height is 240 - The FCEUmm core's max width is 256 (602 when using NTSC Filters) - The FCEUmm core's max height is 240 - The FCEUmm core's core provided aspect ratio is 4:3 DAR or 8:7 PAR ### Custom color palettes To use custom color palettes in the FCEUmm core, the ['Color Palette' core option](#core-options) must be set to custom and the custom color palette file you want to use must be in RetroArch's system directory. Make sure the custom palette file is named 'nes.pal' Custom color palettes for the NES can be generated with either of these tools. - [Bisqwit's NTSC NES palette generator](http://bisqwit.iki.fi/utils/nespalette.php) - [Drag's NTSC NES palette generator](http://drag.wootest.net/misc/palgen.html) ## Core options The FCEUmm core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Region** [fceumm_region] (**Auto**|NTSC|PAL|Dendy) Force core to use NTSC, PAL or Dendy system audio / video timings. - **Preferred aspect ratio** [fceumm_aspect] (**8:7 PAR**|4:3) Choose the preferred aspect ratio. RetroArch's aspect ratio must be set to Core provided in the Video settings. ??? note "Preferred aspect ratio - 8:7 PAR" ![](../image/core/fceumm/8by7_PAR.png) ??? note "Preferred aspect ratio - 4:3" ![](../image/core/fceumm/4by3.png) - **Color Palette** [fceumm_palette] (**default**|asqrealc|nintendo-vc|rgb|yuv-v3|unsaturated-final|sony-cxa2025as-us|pal|bmf-final2|bmf-final3|smooth-fbx|composite-direct-fbx|pvm-style-d93-fbx|ntsc-hardware-fbx|nes-classic-fbx-fs|nescap|wavebeam|raw|custom) Choose which color palette is going to be used. The raw palette can used in combination with the nes-decoder shader to give colors based off on Bisqwit's NES palette generator and applies either an FCC color conversion matrix or specific Sony US matrix. !!! attention "Disclaimer" These 'Color Palette core option screenshots have been taken with the 'Use NTSC Palette' core option set to Off. ??? note "Color Palette - default" ![](../image/core/fceumm/default.png) ??? note "Color Palette - asqrealc" ![](../image/core/fceumm/asqrealc.png) ??? note "Color Palette - nintendo-vc" ![](../image/core/fceumm/nintendo_vc.png) ??? note "Color Palette - rgb" ![](../image/core/fceumm/rgb.png) ??? note "Color Palette - yuv-v3" ![](../image/core/fceumm/yuv_v3.png) ??? note "Color Palette - unsaturated-final" ![](../image/core/fceumm/unsaturated_final.png) ??? note "Color Palette - sony-cxa2025as-us" ![](../image/core/fceumm/sony_cxa2025as_us.png) ??? note "Color Palette - pal" ![](../image/core/fceumm/pal.png) ??? note "Color Palette - bmf-final2" ![](../image/core/fceumm/bmf_final2.png) ??? note "Color Palette - bmf-final3" ![](../image/core/fceumm/bmf_final3.png) ??? note "Color Palette - smooth-fbx" ![](../image/core/fceumm/smooth_fbx.png) ??? note "Color Palette - composite-direct-fbx" ![](../image/core/fceumm/direct_fbx.png) ??? note "Color Palette - pvm-style-d93-fbx" ![](../image/core/fceumm/pvm_style_d93_fbx.png) ??? note "Color Palette - ntsc-hardware-fbx" ![](../image/core/fceumm/ntsc_hardware_fbx.png) ??? note "Color Palette - nes-classic-fbx-fs" ![](../image/core/fceumm/nes_classic_fbx_fs.png) ??? note "Color Palette - nescap" ![](../image/core/fceumm/nescap.png) ??? note "Color Palette - wavebeam" ![](../image/core/fceumm/wavebeam.png) ??? note "Color Palette - raw" ![](../image/core/fceumm/raw.png) - **Allow Opposing Directions** [fceumm_up_down_allowed] (**disabled**|enabled) Enabling this will allow pressing / quickly alternating / holding both left and right (or up and down in some games) directions at the same time. This may cause movement based glitches to occur in certain games. It's best to keep this core option disabled. - **Crop Overscan (Horizontal)** [fceumm_overscan_h] (**disabled**|enabled) Crop out (horizontally) the potentially random glitchy video output that would have been hidden by the bezel around the edge of a standard-definition television screen. ??? note "Crop Overscan (Horiontal) - Off" ![](../image/core/fceumm/horiz_off.png) ??? note "Crop Overscan (Horizontal) - On" ![](../image/core/fceumm/horiz_on.png) - **Crop Overscan (Vertical)** [fceumm_overscan_v] (**enabled**|disabled) Crop out (vertically) the potentially random glitchy video output that would have been hidden by the bezel around the edge of a standard-definition television screen. ??? note "Crop Overscan (Vertical) - On" ![](../image/core/fceumm/vert_on.png) ??? note "Crop Overscan (Vertical) - Off" ![](../image/core/fceumm/vert_off.png) - **No Sprite Limit** [fceumm_nospritelimit] (**disabled**|enabled) Removes 8-sprites-per-scanline hardware limit. - **Sound Volume** [fceumm_sndvolume] (0|1|2|3|4|5|6|**7**|8|9|10) Self-explanatory. - **Sound Quality** [fceumm_sndquality] (**Low**|High|Very High) Enables high/higher sound quality for games using expansion audio (MMC5, VRC6, VRC7, Namco, Sunsoft). Use Low for slower devices. - **Swap Duty Cycles** [fceumm_swapduty] (**disabled**|enabled) Replicates the sound of some famiclones that have duty cycles swapped for square channels. A quick sound comparison is in Contra's sound effect when shooting with normal bullets. - **Turbo Enable** [fceumm_turbo_enable] (**None**|Player 1|Player 2|Both) Enable the use of the [Turbo B and Turbo A buttons](#controllers). - **Turbo Delay (in frames)** [fceumm_turbo_delay] (**3**|5|10|15|30|60|1|2) The number of frames between consecutive button presses when the Turbo B or Turbo A buttons are held down. - **Zapper Mode** [fceumm_zapper_mode] (**lightgun**|touchscreen|mouse) Pointer allows the Zapper Device Type to be used for touch-devices, but still can be used with regular mouse. Pointer and Mouse mode movement behaves differently with different input driver so user can choose which movement feels natural to them. - **Show Crosshair** [fceumm_show_crosshair] (**enabled**|disabled) Show the crosshair for the Zapper device type. ??? note "Show Crosshair - On" ![](../image/core/fceumm/cross_on.png) ??? note "Show Crosshair - Off" ![](../image/core/fceumm/cross_off.png) - **Overclocking** [fceumm_overclocking] (**disabled**|2x-Postrender|2x-VBlank) Overclocks the NES using PPU method to minimize ingame slowdowns of some games. Contra Force needs VBlank mode (stage 3 slowdowns). Choose which ever minimizes slowdowns without image distortion. - **RAM power up state (Restart)** [fceumm_ramstate] (**$FF**|$00|random) Choose RAM startup during power up. Fill the ram with either $FF, $00 or random. Some games rely on initial ram values for random generator as an example. Some unlicensed carts and rom hacks prefers $00 or else rom will not boot up or causes graphics glitches or any other problems. - **NTSC Filter** [fceumm_ntsc_filter] (**disabled**|composite|svideo|rgb|monochrome) Enable blargg NTSC filters. !!! attention "Disclaimer" These 'NTSC Filter' core option screenshots have been taken with the 'Color Palette' core option set to smooth-fbx. ??? note "NTSC Filter - Off" ![](../image/core/fceumm/blargg_off.png) ??? note "NTSC Filter - composite (color bleeding + artifacts)" ![](../image/core/fceumm/blargg_composite_normal.png) ??? note "NTSC Filter - svideo (color bleeding only)" ![](../image/core/fceumm/blargg_svideo_normal.png) ??? note "NTSC Filter - rgb (crisp image)" ![](../image/core/fceumm/blargg_rgb_normal.png) ??? note "NTSC Filter - monochrome (desaturated + artifacts)" ![](../image/core/fceumm/blargg_monochrome_normal.png) - **Show Advanced System Options** [fceumm_show_adv_system_options] (**disabled**|enabled) Show advanced system options and tweaks. - **Show Advanced Sound Options** [fceumm_show_adv_sound_options] (**disabled**|enabled) Show advanced sound controls and tweaks. ## Controllers The FCEUmm core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Input disabled. - **Auto** - Joypad - Based off the loaded game's crc, the core will automatically select a regular controller (NES or Famicom) for User 1. - [Gamepad](http://nintendo.wikia.com/wiki/Nintendo_Entertainment_System_controller) - Joypad - Manually selects a regular controller (NES or Famicom) for User 1. - [Zapper](http://nintendo.wikia.com/wiki/NES_Zapper) - Mouse - Manually selects a Zapper light gun (NES or Famicom) for User 1. **NOTE 1: Zapper connected to user 1 is only required on VS Unisystem games. You will hear a loud alarm when a game requires one and no zapped device is selected or the game's CRC fails to match existing database for autodetection.** ### User 2 device types - None - Input disabled. - **Auto** - Joypad - Based off the loaded game's crc, the core will automatically select a regular controller (NES or Famicom) or a Zapper light gun (NES or Famicom) or a Arkanoid Paddle (NES only) for User 2. - [Gamepad](http://nintendo.wikia.com/wiki/Nintendo_Entertainment_System_controller) - Joypad - Manually selects a regular controller (NES or Famicom) for User 2. - [Arkanoid](https://en.wikipedia.org/wiki/Arkanoid_Controller) - Mouse - Manually selects a Arkanoid Paddle (NES only) for User 2. - [Zapper](http://nintendo.wikia.com/wiki/NES_Zapper) - Mouse - Manually selects a Zapper light gun (NES or Famicom) for User 2. **NOTE 2: Zapper connected to user 2 is required for most cases. See note 1 above.** ### User 3 and 4 device types - used for multitap - None - Input disabled. - **Auto** - Joypad - Based off the loaded game's crc, the core will automatically select a regular controller (NES or Famicom) for User 3 and/or 4 in multitap games. - [Gamepad](http://nintendo.wikia.com/wiki/Nintendo_Entertainment_System_controller) - Joypad - Manually selects a regular controller (NES or Famicom) for User 3/4. ### Other controllers (User 5 device type) The FCEUmm core will also auto select the following controllers for the **Famicom** based off the loaded game's crc. - [Arkanoid Paddle (Famicom)](https://en.wikipedia.org/wiki/Arkanoid_Controller) - Mouse - Bandai Hyper Shot Gun (Famicom) - Mouse - Oeka Kids Tablet (Famicom) - Mouse - 4-Player Adaptor - force enable multitap mode ### Multitap support The FCEUmm core supports up to 4 players in multitap games for the NES and Famicom, games with multitap usage are detected by their crc. Multitap can be manually enabled if selecting **4-Player Adaptor** in **User 5 Device type**. ### Controller tables #### Joypad ![](../image/controller/nes.png) !!! warning In order to use the Turbo A and Turbo B buttons, the 'Turbo Enable' core option must be set to On. | User 1 Remap descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Turbo B | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | Turbo A | ![](../image/retropad/retro_x.png) | | (FDS) Disk Side Change | ![](../image/retropad/retro_l1.png) | | (FDS) Insert/Eject Disk | ![](../image/retropad/retro_r1.png) | | (VSSystem) Insert Coin | ![](../image/retropad/retro_r2.png) | | User 2 - 4 Remap descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Turbo B | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | Turbo A | ![](../image/retropad/retro_x.png) | #### Mouse | RetroMouse Inputs | Zapper | Arkanoid | Oeka Kids Tablet | Bandai Hyper Shot Gun | |---------------------------------------------------------------------------------------------------------|------------------|-------------------|-------------------------|---------------------------------| | ![](../image/retromouse/retro_mouse.png) or ![](../image/Button_Pack/Gestures/Gesture_Finger_Front.png) | Zapper Crosshair | Arkanoid Movement | Oeka Kids Tablet Cursor | Bandai Hyper Shot Gun Crosshair | | ![](../image/retromouse/retro_left.png) or ![](../image/Button_Pack/Gestures/Gesture_Tap.png) | Zapper Trigger | Arkanoid Fire | Oeka Kids Tablet Touch | Bandai Hyper Shot Gun Trigger | - When the 'Zapper Mode' core option is set to lightgun, the 'Zapper' device type can be controlled with lightgun inputs (such as Wii remote). - When the 'Zapper Mode' core option is set to touchscreen, the 'Zapper' device type can be controlled with touch inputs. - When the 'Zapper Mode' core option is set to mouse, the 'Zapper' device type can be controlled with mouse inputs. ## Compatibility | Game | Issue | |------------------------------|--------------------------------------------------------------| | Skull & Crossbones | Graphical glitches and screen shaking when in 2-player mode. | ## External Links - [Official FCEUmm Website](http://cah4e3.shedevr.org.ru/fceultra.php) - [Official FCEUmm Sourceforge Repository](https://sourceforge.net/projects/fceumm/) - [Libretro FCEUmm Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/fceumm_libretro.info) - [Libretro FCEUmm Github Repository](https://github.com/libretro/libretro-fceumm) - [Report Libretro FCEUmm Core Issues Here](https://github.com/libretro/libretro-fceumm/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0IfFhmpqSJMJgst6QCsWwxdD) ## Other Links - [NES Header Database](http://nes.dnsabr.com/) - Verify, remove or add headers for known No-Intro roms. ### See also #### Nintendo - Family Computer Disk System - [Nintendo - NES / Famicom (Mesen)](mesen.md) - [Nintendo - NES / Famicom (Nestopia)](nestopia.md) #### Nintendo - Nintendo Entertainment System - [Nintendo - NES / Famicom (bnes)](bnes.md) - [Nintendo - NES / Famicom (Emux NES)](emux_nes.md) - [Nintendo - NES / Famicom (Mesen)](mesen.md) - [Nintendo - NES / Famicom (Nestopia)](nestopia.md) - [Nintendo - NES / Famicom (QuickNES)](quicknes.md) ================================================ FILE: docs/library/ffmpeg.md ================================================ # FFmpeg ## Background Video/music player implemented in libretro. FFmpeg can play video and audio files of different formats in RetroArch. If a video file has more than one audio input, FFmpeg can switch between them. If there is a hard coded subtitle file in the video file, FFmpeg can switch between them in the same way. ### Author/License The FFmpeg core has been authored by - Fabrice Bellard - FFmpeg team The FFmpeg core is licensed under - [LGPLv2, GPLv2](https://github.com/libretro/FFmpeg/blob/master/LICENSE.md) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Experience !!! important RetroArch and LibRetro do not share any copyrighted content. RetroArch does not download any video or audio files. It does not stream content you have on different platforms. ### Watching Movies with Subtitles You can open video files in the following formats(see: [Extensions](../ffmpeg/#extensions)). If your video file in these formats has a subtitle file encoded with .SSA type, these subtitle files will appear automatically. External subtitles are currently not supported. The video files you have played will be added to the Videos section in the main menu. ??? note "Turkish subtitles encoded 95's Ghost in the Shell" ![RetroArch and LibRetro do not share any copyrighted content.](../image/core/ffmpeg/subtitle.png) #### Setup Watch the video below for details: ### Listening to Music You can open audio files in the following formats (see: [Extensions](../ffmpeg/#extensions)). In the example below, you can see and listen to an mp3 file running at the lowest settings. File quality will affect sound quality. The audio files you have played will be added to the Music section in the main menu. ??? note "Example" #### Setup Watch the video below for details: ## Extensions Content that can be loaded by the FFmpeg core have the following file extensions: - .mkv - .avi - .f4v - .f4f - .3gp - .ogm - .flv - .mp4 - .mp3 - .flac - .ogg - .m4a - .webm - .3g2 - .mov - .wmv - .mpg - .mpeg - .vob - .asf - .divx - .m2p - .m2ts - .ps - .ts - .mxf - .wma - .wav ## Features Frontend-level settings or features that the FFmpeg core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | [Shaders](../ffmpeg/#shaders) | ✔ | | Saves | ✕ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The FFmpeg core's directory name is 'FFmpeg' ### Geometry and timing - The FFmpeg core's core provided FPS is dependant on the loaded media. - The FFmpeg core's core provided sample rate is dependant on the loaded media. - The FFmpeg core's core provided aspect ratio is dependant on the loaded media. ### Shaders Shaders can improve your viewing quality as well as deliver the excitement of the 80s or 90s. In the example below you can see how a VHS shader can affect view quality. You can also provide more innovative watching possibilities by stacking shaders on top of each other. ??? note "VHSPro Shader" ![RetroArch and LibRetro do not share any copyrighted content.](../image/core/ffmpeg/shader1.png) ## Core options The FFmpeg core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Temporal Interpolation** [ffmpeg_temporal_interp] (**Off**/On) 'Fake’ a higher framerate by using motion blur. - **FFT Resolution** [ffmpeg_fft_resolution] (**1280x720**/1920x1080/2560x1440/3840x2160/640x360/320x180) Modify the resolution of the music visualizer. ??? note "FFT Resolution - 320x180" ![](../image/core/ffmpeg/320x180.png) ??? note "FFT Resolution - 3840x2160" ![](../image/core/ffmpeg/3840x2160.png) - **FFT Multisample** [ffmpeg_fft_multisample] (**1x**/2x/4x) Modify the antialiasing of the music visualizer. - **Colorspace** [ffmpeg_color_space] (**auto**/BT.70/BT.601/FCC/SMPTE240M) Choose [colorspaces](https://trac.ffmpeg.org/wiki/colorspace) from different broadcast regions/standards. ??? note "Colorspace" ![](../image/core/ffmpeg/BT.601.png) ![](../image/core/ffmpeg/FCC.png) ![](../image/core/ffmpeg/BT.709.png) ![](../image/core/ffmpeg/SMPTE240M.png) ## Controllers The FFmpeg core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. - **RetroPad** - Joypad - RetroPad w/Analog - Joypad - There's no reason to switch to this. ### Other controllers - Mouse - The FFmpeg core allows Wheel Up and Wheel Down mouse inputs for seeking. This is always active, completely separate from the device types in the Controls menu and cannot be manually selected. ### Controller tables #### Joypad | User 1 Remap descriptors | RetroPad Inputs | |--------------------------|------------------------------------------------| | Seek +60 seconds | ![](../image/retropad/retro_dpad_up.png) | | Seek -60 seconds | ![](../image/retropad/retro_dpad_down.png) | | Seek -10 seconds | ![](../image/retropad/retro_dpad_left.png) | | Seek +10 seconds | ![](../image/retropad/retro_dpad_right.png) | | Cycle Audio Track | ![](../image/retropad/retro_l1.png) | | Cycle Subtitle Track | ![](../image/retropad/retro_r1.png) | #### Mouse | RetroMouse Inputs | FFmpeg Core Inputs | |-----------------------------------------------------|---------------------------| | Wheel Up | Seek +60 seconds | | Wheel Down | Seek -60 seconds | ## External Links - [Official FFmpeg Website](https://www.ffmpeg.org/) - [Official FFmpeg Repositories](https://www.ffmpeg.org/download.html#repositories) - [Libretro FFmpeg Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/ffmpeg_libretro.info) - [Internal Libretro FFmpeg Github Repository](https://github.com/libretro/RetroArch/tree/master/cores/libretro-ffmpeg) - [Buildbot Libretro FFmpeg Github repository](https://github.com/libretro/FFmpeg) - [Report Libretro FFmpeg Core Issues Here](https://github.com/libretro/RetroArch/issues) - [Video Setup](https://www.youtube.com/watch?v=zget1P8ptho) - [Audio Setup](https://www.youtube.com/watch?v=5f6nWBpagaM) ================================================ FILE: docs/library/flycast.md ================================================ # Sega - Dreamcast/NAOMI (Flycast) ## Background Flycast is a multi-platform Sega Dreamcast, NAOMI, Atomiswave and System SP emulator. The Flycast core has been authored by - flyinghead The Flycast core is licensed under - [GPLv2](https://github.com/flyinghead/flycast/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## How to play NAOMI Games 1. Run NAOMI games stored in MAME format zip files by following the same process as standard Dreamcast games 2. Run NAOMI GD-ROM format games stored in MAME zip + chd format by running the zip file through RetroArch. The zip file should be stored in your roms folder with the chd file in a subdirectory of the roms folder named after the mame ID. {== Example (MAME ID=ikaruga) - [ROM FOLDER]/ikaruga.zip - [ROM FOLDER]/ikaruga/gdl-0010.chd ==} ## Extensions Content that can be loaded by the flycast core have the following file extensions: - .cdi - .gdi - .chd - .cue - .bin - .elf - .zip - .7z - .lst - .dat - .m3u ## Databases RetroArch database(s) that are associated with the flycast core: - [Sega - Dreamcast](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20Dreamcast.rdb) ## BIOS Required or optional firmware files go in RetroArch's system directory. | Filename | Description | md5sum | |:---------------:|:--------------------------------------------------------------------:|:--------------------------------:| | dc/dc_boot.bin | Dreamcast BIOS - Optional | e10c53c2f8b90bab96ead2d368858623 | | dc/naomi.zip | NAOMI BIOS from MAME - Optional | | | dc/hod2bios.zip | NAOMI The House of the Dead 2 BIOS from MAME - Optional | | | dc/f355dlx.zip | NAOMI Ferrari F355 Challenge (deluxe) BIOS from MAME - Optional | | | dc/f355bios.zip | NAOMI Ferrari F355 Challenge (twin/deluxe) BIOS from MAME - Optional | | | dc/airlbios.zip | NAOMI Airline Pilots (deluxe) BIOS from MAME - Optional | | | dc/awbios.zip | Atomiswave BIOS from MAME - Optional | | | dc/naomi2.zip | NAOMI 2 BIOS from MAME - Optional | | | dc/segasp.zip | System SP BIOS from MAME - Optional | | !!! attention All bios files need to be in a directory named 'dc' in RetroArch's system directory. ## Features | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✔ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | Softpatching | ✕ | | Disk Control | ✔ | | Username | ✕ | | Crop Overscan (in RetroArch's Video settings) | ✕ | ### Directories The FlyCast core's directory name is 'Flycast' The FlyCast core creates these files in RetroArch's system directory. ``` dc/ ├── vmu_save_A1.bin ├── vmu_save_B1.bin ├── vmu_save_C1.bin ├── vmu_save_D1.bin └── dc_nvmem.bin ``` ### Core provided aspect ratio FlyCast's core provided aspect ratio is 4/3. ### Rumble Rumble only works when the Joypad being used has rumble functionality and the Joypad input driver being used has rumble function implementation (e.g. **Xinput**). ## Core options The FlyCast core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. ### System Configure region, language, BIOS and base hardware settings. **Region** [flycast_region] (**Default**|Japan|USA|Europe) **Language** [flycast_language] (**Default**|Japanese|English|German|French|Spanish|Italian) !!! regular "" Changes the language used by the BIOS and by any games that contain multiple languages. **HLE BIOS** [flycast_hle_bios] (**disabled**|enabled) !!! regular "" Force use of high-level emulation BIOS. **Boot to BIOS** [flycast_boot_to_bios] (**disabled**|enabled) !!! regular "" Boot directly into the Dreamcast BIOS menu. **Enable DSP** [flycast_enable_dsp] (**enabled**|disabled) !!! regular "" Enable emulation of the Dreamcast's audio DSP (digital signal processor). Improves the accuracy of generated sound, but increases performance requirements. **Force Windows CE Mode** [flycast_force_windows_ce_modee] (**disabled**|enabled) !!! regular "" Enable full MMU (Memory Management Unit) emulation and other settings for Windows CE games. ### Video Configure visual buffers & effects, display parameters, framerate/-skip and rendering/texture parameters. **Internal resolution (restart)** [flycast_internal_resolution] (**640x480**|1280x960|1920x1440|2560x1920|3200x2400|3840x2880| 4480x3360|5120x3840|5760x4320|6400x4800|7040x5280|7680x5760|8320x6240|8960x6720| 9600x7200|10240x7680|10880x8160|11520x8640|12160x9120|12800x9600) !!! regular "" Modify rendering resolution. ??? note "Internal resolution - 640x480" ![](../image/core/flycast/640x480.png) ??? note "Internal resolution - 1920x1440" ![](../image/core/flycast/1920x1440.png) **Cable Type** [flycast_cable_type] (**TV (Composite)**[^cable]|TV (RGB)|VGA(RGB)) !!! regular "" The output signal type. 'TV (Composite)' is the most widely supported. **Broadcast Standard** [flycast_brodcast] (**Default**|PAL-M (Brazil)|PAL-N (Argentina, Paraguay, Uruguay)|NTSC|PAL (World)) **Screen Orientation** [flycast_screen_orientation] (**Horizontal**|Vertical) **Alpha Sorting** [flycast_alpha_sorting] (Per-Strip (fast, least accurate)|Per-Triangle (normal)|"Per-Pixel (accurate, but slowest)[^vulkan]) **Enable RTT (Render To Texture) Buffer** (**Off**|On) **Mipmapping** (Off|**On**) **Volume modifier** (**On**|off) !!! regular "" A GPU feature that is typically used by games to draw shadows of objects. You should typically leave this on - performance impact should be minimal to negligible. **Anisotropic Filtering** [flycast_anistropic_filtering] (**4**|2|8|16) !!! regular "" Enhance the quality of textures on surfaces that are at oblique viewing angles with respect to the camera. **Delay Frame Swapping** [flycast_delay_frame_swapping] (**disabled**|enabled) !!! regular "" Useful to avoid flashing screens or glitchy videos. Not recommended on slow platforms. Note: This setting only applies when 'Threaded Rendering' is enabled. **PowerVR2 Post-processing Filter** [flycast_pvr2_filtering] (**disabled**|enabled) !!! regular "" Post-process the rendered image to simulate effects specific to the PowerVR2 GPU and analog video signals. ### Performance Configure threaded rendering, integer division optimisations and frame skip settings **Threaded Rendering (Restart Required)** [flycast_threaded_rendering] (**enabled**|disabled) !!! regular "" Runs the GPU and CPU on different threads. Highly recommended. **Auto Skip Frame** [flycast_skip_frame] (**disabled**|enabled) !!! regular "" Automatically skip frames when the emulator is running slow. Note: This setting only applies when 'Threaded Rendering' is enabled. **Frame Skipping** [flycast_frame_skipping] (**disabled**|1|2|3|4|5|6) !!! regular "" Sets the number of frames to skip between each displayed frame. **Widescreen Cheats (Restart Required)** [flycast_widescreen_cheats] (**Off**|On) !!! regular "" Activates cheats that allow certain games to display in widescreen format. **Widescreen Hack** [flycast_widescreen_hack] (**Off**|On) !!! regular "" Draw geometry outside of the normal 4:3 aspect ratio. May produce graphical glitches in the revealed areas. **GD-ROM Fast Loading (inaccurate)** [flycast_gdrom_fast_loading] (**On**|Off) !!! regular "" Speeds up GD-ROM loading. **Load Custom Textures** [flycast_custom_textures] (**Off**|On) **Dump Textures** [flycast_dump_textures] (**Off**|On) ### Input !!! regular "" Configure gamepad and light gun settings. **Analog Stick Deadzone** [flycast_analog_stick_deadzone] (**15%**|0%|5%|10%|20%|25%|30%) **Trigger Deadzone** [flycast_trigger_deadzone] (**0%**|5%|10%|15%|20%|25%|30%) **Digital Triggers** [flycast_digital_triggers] (**Off**|On) **Purupuru Pack/Vibration Pack** [flycast_enable_purupuru] (**On**|Off) !!! regular "" Enables controller force feedback. **Gun crosshair 1 Display** [flycast_lightgun1_crosshair] (**Off**|White|Red|Green|Blue) **Gun crosshair 2 Display** [flycast_lightgun2_crosshair] (**Off**|White|Red|Green|Blue) **Gun crosshair 3 Display** [flycast_lightgun3_crosshair] (**Off**|White|Red|Green|Blue) **Gun crosshair 4 Display** [flycast_lightgun4_crosshair] (**Off**|White|Red|Green|Blue) ### Visual Memory Unit !!! regular "" Configure per-game VMU save files and on-scren VMU visibility sttings. **Per-Game VMUs** [flycast_per_content_vmus] (**disabled**|VMU A1|All VMUs) !!! regular "" When disabled, all games share 4 VMU save files (A1, B1, C1, D1) located in RetroArch's system directory. The 'VMU A1' setting creates a unique VMU 'A1' file in RetroArch's save directory for each game that is launched. The 'All VMUs' setting creates 4 unique VMU files (A1, B1, C1, D1) for each game that is launched. **VMU Screen 1 Display** [flycast_vmu1_screen_display] (**Off**|enabled) **VMU Screen 1 Position** [flycast_vmu1_screen_position] (**Upper Left**|Upper Right|Lower Left|Lower Right) **VMU Screen 1 Size** [flycast_vmu1_screen_size] (**1x**|2x|3x|4x|5x) **VMU Screen 1 Pixel On Color** [flycast_vmu1_pixel_on_color] (**Default ON**|Default OFF|Black|Blue|Light Blue|Green|Cyan|Cyan Blue|Light Green|Cyan Green|Light Cyan|Red|Purple|Light Purple|Yellow|Gray|Light Purple (2)|Light Green (2)|Light Green (3)|Light Cyan (2)|Light Red(2)|Magenta|Light Purple (3)|Light Oragen|Orange|Light Purple(4)|Light Yellow|Light Yellow (2)|White) **VMU Screen 1 Pixel Off Color** [flycast_vmu1_pixel_off_color] (**Default OFF**|Default ON|Black|Blue|Light Blue|Green|Cyan|Cyan Blue|Light Green|Cyan Green|Light Cyan|Red|Purple|Light Purple|Yellow|Gray|Light Purple (2)|Light Green (2)|Light Green (3)|Light Cyan (2)|Light Red(2)|Magenta|Light Purple (3)|Light Oragen|Orange|Light Purple(4)|Light Yellow|Light Yellow (2)|White) **VMU Screen 1 Opacity** [flycast_vmu1_screen_opacity] (**100%**|10%|20%|30%|40%|50%|60%|70%|80%|90%) **VMU Screen 2 Display** [flycast_vmu2_screen_display] (**Off**|enabled) **VMU Screen 2 Position** [flycast_vmu2_screen_position] (**Upper Left**|Upper Right|Lower Left|Lower Right) **VMU Screen 2 Size** [flycast_vmu2_screen_size] (**1x**|2x|3x|4x|5x) **VMU Screen 2 Pixel On Color** [flycast_vmu2_pixel_on_color] (**Default ON**|Default OFF|Black|Blue|Light Blue|Green|Cyan|Cyan Blue|Light Green|Cyan Green|Light Cyan|Red|Purple|Light Purple|Yellow|Gray|Light Purple (2)|Light Green (2)|Light Green (3)|Light Cyan (2)|Light Red(2)|Magenta|Light Purple (3)|Light Oragen|Orange|Light Purple(4)|Light Yellow|Light Yellow (2)|White) **VMU Screen 2 Pixel Off Color** [flycast_vmu2_pixel_off_color] (**Default OFF**|Default ON|Black|Blue|Light Blue|Green|Cyan|Cyan Blue|Light Green|Cyan Green|Light Cyan|Red|Purple|Light Purple|Yellow|Gray|Light Purple (2)|Light Green (2)|Light Green (3)|Light Cyan (2)|Light Red(2)|Magenta|Light Purple (3)|Light Oragen|Orange|Light Purple(4)|Light Yellow|Light Yellow (2)|White) **VMU Screen 2 Opacity** [flycast_vmu2_screen_opacity] (**100%**|10%|20%|30%|40%|50%|60%|70%|80%|90%) **VMU Screen 3 Display** [flycast_vmu3_screen_display] (**Off**|enabled) **VMU Screen 3 Position** [flycast_vmu3_screen_position] (**Upper Left**|Upper Right|Lower Left|Lower Right) **VMU Screen 3 Size** [flycast_vmu3_screen_size] (**1x**|2x|3x|4x|5x) **VMU Screen 3 Pixel On Color** [flycast_vmu3_pixel_on_color] (**Default ON**|Default OFF|Black|Blue|Light Blue|Green|Cyan|Cyan Blue|Light Green|Cyan Green|Light Cyan|Red|Purple|Light Purple|Yellow|Gray|Light Purple (2)|Light Green (2)|Light Green (3)|Light Cyan (2)|Light Red(2)|Magenta|Light Purple (3)|Light Oragen|Orange|Light Purple(4)|Light Yellow|Light Yellow (2)|White) **VMU Screen 3 Pixel Off Color** [flycast_vmu3_pixel_off_color] (**Default OFF**|Default ON|Black|Blue|Light Blue|Green|Cyan|Cyan Blue|Light Green|Cyan Green|Light Cyan|Red|Purple|Light Purple|Yellow|Gray|Light Purple (2)|Light Green (2)|Light Green (3)|Light Cyan (2)|Light Red(2)|Magenta|Light Purple (3)|Light Oragen|Orange|Light Purple(4)|Light Yellow|Light Yellow (2)|White) **VMU Screen 3 Opacity** [flycast_vmu3_screen_opacity] (**100%**|10%|20%|30%|40%|50%|60%|70%|80%|90%) **VMU Screen 4 Display** [flycast_vmu4_screen_display] (**Off**|enabled) **VMU Screen 4 Position** [flycast_vmu4_screen_position] (**Upper Left**|Upper Right|Lower Left|Lower Right) **VMU Screen 4 Size** [flycast_vmu4_screen_size] (**1x**|2x|3x|4x|5x) **VMU Screen 4 Pixel On Color** [flycast_vmu4_pixel_on_color] (**Default ON**|Default OFF|Black|Blue|Light Blue|Green|Cyan|Cyan Blue|Light Green|Cyan Green|Light Cyan|Red|Purple|Light Purple|Yellow|Gray|Light Purple (2)|Light Green (2)|Light Green (3)|Light Cyan (2)|Light Red(2)|Magenta|Light Purple (3)|Light Oragen|Orange|Light Purple(4)|Light Yellow|Light Yellow (2)|White) **VMU Screen 4 Pixel Off Color** [flycast_vmu4_pixel_off_color] (**Default OFF**|Default ON|Black|Blue|Light Blue|Green|Cyan|Cyan Blue|Light Green|Cyan Green|Light Cyan|Red|Purple|Light Purple|Yellow|Gray|Light Purple (2)|Light Green (2)|Light Green (3)|Light Cyan (2)|Light Red(2)|Magenta|Light Purple (3)|Light Oragen|Orange|Light Purple(4)|Light Yellow|Light Yellow (2)|White) **VMU Screen 4 Opacity** [flycast_vmu4_screen_opacity] (**100%**|10%|20%|30%|40%|50%|60%|70%|80%|90%) ## Controllers ### Device types The Flycast core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): #### User 1 - 4 device types - None - Input disabled. - **RetroPad** - Joypad - RetroPad w/Analog - Joypad - **There is no reason to switch to this.** ### Controller tables #### Joypad and analog device type table ![](../image/controller/dc.png) | User 1 - 4 input descriptors | | RetroPad | |------------------------------|---------------------------------------------|--------------------| | A | ![](../image/retropad/retro_b.png) | A | | X | ![](../image/retropad/retro_y.png) | X | | Start | ![](../image/retropad/retro_start.png) | Start | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | | B | ![](../image/retropad/retro_a.png) | B | | Y | ![](../image/retropad/retro_x.png) | Y | | L (fierce) | ![](../image/retropad/retro_l1.png) | L (fierce) | | R (fierce) | ![](../image/retropad/retro_r1.png) | R (fierce) | | L (weak) | ![](../image/retropad/retro_l2.png) | L (weak) | | R (weak) | ![](../image/retropad/retro_r2.png) | R (weak) | | Analog X | ![](../image/retropad/retro_left_stick.png) X | Analog X | | Analog Y | ![](../image/retropad/retro_left_stick.png) Y | Analog Y | ## Multiple-disc games If foo is a multiple-disc game, you should have .chd/cue/cdi/gdi files for each one, e.g. `foo (Disc 1).chd`, `foo (Disc 2).chd`, `foo (Disc 3).chd`. To take advantage of Flycast's Disk Control feature for disk swapping, an index file (a m3u file) should be made. Create a text file and save it as `foo.m3u`. Then enter your game's .chd/cue/cdi/gdi files on it. The m3u file contents should look something like this: `foo.m3u` ``` foo (Disc 1).chd foo (Disc 2).chd foo (Disc 3).chd ``` After that, you can load the `foo.m3u` file in RetroArch with the Flycast core. An alternative is to append discs to the current playlist via the "Disk Image Append" option in the Disk Control RetroArch menu. ## Compatibility ### General Flycast Issues - If the date and time are not being saved properly, please ensure you have the correct dc_flash.bin and dc_bios.bin files (check the md5sum values). Also try deleting all of the dc_nvmem.bin files in the system/dc directory. - Once you save to a VMU slot with any game, that VMU becomes inaccessible the next time you load the emulator. The fix for this is to enable the Core Option for "Boot to BIOS", exit RA, delete all of the vmu_save*.bin files, start RA/Flycast. It will boot to BIOS where you can select the VMU option, select one of the VMUs, click the "All" icon in upper-left, click Delete All and the VMU will be formatted/intialized. Disable the "Boot to BIOS" option, restart RA, and everything should be fine. - Polygon sorting issues can make objects appear distorted. Use Per-Pixel Alpha sorting for accurate rendering (at the expense of performance). - When using an Xbox 360 Controller, analog triggers don't work properly. Use the bumpers instead. - Changing games without closing and reloading RetroArch often leads to RetroArch crashing. | Game | Issue | |---------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Crazy Taxi (PAL) | Player taxis do not emit engine sounds. | | Crazy Taxi (USA) | Player taxis do not emit engine sounds. | | | Jet Grind Radio (USA) | Police reports during levels do not display correctly. | | Sonic Adventure (PAL) | Must be set to use "VGA" output in core options, as "TV" mode will cause all subsequent FMV to make RetroArch become unresponsive. | | Unreal Tournament (USA) | Set Cable Type to 'VGA (RGB)', otherwise the game will crash at start. | ## External Links - [Libretro Flycast Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/flycast_libretro.info) - [Flycast Github Repository](https://github.com/flyinghead/flycast) - [Report Flycast Issues Here](https://github.com/flyinghead/flycast/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0Ic597IBX8lXnsCV5ozweGbp) - [Steam page](https://store.steampowered.com/app/1222633/RetroArch___Flycast/) [^vulkan]: If video driver is vulkan. [^cable]: If low end then VGA (RGB), otherwise TV (Composite). ================================================ FILE: docs/library/fmsx.md ================================================ # MSX (fMSX) ## Background This is a port of Marat Fayzullin's fMSX 6.0 (21-Feb-2021) to the libretro API. fMSX is a program that emulates MSX, MSX2, and MSX2+ 8bit home computers. It runs MSX/MSX2/MSX2+ software on many different platforms including Windows, Android, Symbian, MacOS, Unix, MSDOS, AmigaOS, etc. I started developing fMSX in 1993 when there were only two other MSX emulators available, both exclusively for MSDOS. From the very beginning, I developed fMSX as a portable program able to run on many different computers. The initial development, for example, was done on DEC Alpha workstations running Unix. Since then, fMSX has seen quite a lot of updates and been ported to many systems. It is still being developed, although not as actively as before because most features are pretty much complete now. The Meteor core has been authored by - Marat Fayzullin The fMSX core is licensed under - [Non-commercial](https://github.com/libretro/fmsx-libretro/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the fMSX core have the following file extensions: - .rom - .mx1 - .mx2 - .dsk - .cas ## Databases RetroArch database(s) that are associated with the fMSX core: - [Microsoft - MSX](https://github.com/libretro/libretro-database/blob/master/rdb/Microsoft%20-%20MSX.rdb) - [Microsoft - MSX2](https://github.com/libretro/libretro-database/blob/master/rdb/Microsoft%20-%20MSX2.rdb) ## BIOS Required or optional firmware files go in RetroArch's system directory. | Filename | Description | md5sum | |:------------:|:-----------------------:|:--------------------------------:| | MSX.ROM | MSX BIOS - Required | 364a1a579fe5cb8dba54519bcfcdac0d | | MSX2.ROM | MSX2 BIOS - Required | ec3a01c91f24fbddcbcab0ad301bc9ef | | MSX2EXT.ROM | MSX2 ExtROM - Required | 2183c2aff17cf4297bdb496de78c2e8a | | MSX2P.ROM | MSX2+ BIOS - Required | 847cc025ffae665487940ff2639540e5 | | MSX2PEXT.ROM |MSX2+ ExtROM - Required | 7c8243c71d8f143b2531f01afa6a05dc | | DISK.ROM | DiskROM/BDOS (optional) | 80dcd1ad1a4cf65d64b7ba10504e8190 | | FMPAC.ROM | FMPAC BIOS (optional) | 6f69cc8b5ed761b03afd78000dfb0e19 | | MSXDOS2.ROM | MSX-DOS 2 (optional) | 6418d091cd6907bbcf940324339e43bb | | PAINTER.ROM | Yamaha Painter (optional) | 403cdea1cbd2bb24fae506941f8f655e | | KANJI.ROM | Kanji Font (optional) | febe8782b466d7c3b16de6d104826b34 | This list of compatible ROMS is not complete. ## Features RetroArch-level settings or features that the fMSX core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | - | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✔ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✔ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | ### Directories The fMSX core's directory name is 'fMSX' The fMSX core saves/loads to/from these directories. **RetroArch's State directory** - 'content-name'.state# (State) ### Geometry and timing - The fMSX core's internal FPS is 60 - The fMSX core's internal sample rate is 48000 Hz - The fMSX core's core provided aspect ratio is (Ratio) ## Core options The fMSX core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **MSX Mode** (**MSX2+**/MSX1/MSX2) Select MSX model. - **MSX Video Mode** (**NTSC**/PAL) Awaiting description. - **MSX Mapper Type Mode** (**Guess Mapper Type A**/Guess Mapper Type B) Awaiting description. - **MSX Main Memory** (**Auto**/64KB/128KB/256KB/512KB) Awaiting description. - **MSX Video Memory** (**Auto**/32KB/64KB/128KB/192KB) Awaiting description. ## Controllers ### Device types The fMSX core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): #### User 1 device types - None - Input disabled. - **Joystick** - Joypad - Joystick + Emulated Keyboard - Joypad - Emulated Keyboard - Joypad - Keyboard - Keyboard - Has Keymapper support #### User 2 device types - None - Input disabled. **Joystick** - Joypad ### Controller tables #### Joypad and analog device type table | User 1 - 2 Remap descriptors for 'Joystick device type'| RetroPad Inputs | |--------------------------|------------------------------------------------| | Fire B | ![](../image/retropad/retro_b.png) | | Stick Up | ![](../image/retropad/retro_dpad_up.png) | | Stick Down | ![](../image/retropad/retro_dpad_down.png) | | Stick Left | ![](../image/retropad/retro_dpad_left.png) | | Stick Right | ![](../image/retropad/retro_dpad_right.png) | | Fire A | ![](../image/retropad/retro_a.png) | | User 1 Remap descriptors for 'Joystick + Emulated Keyboard' device type | RetroPad Inputs | |--------------------------|------------------------------------------------| | Fire B | ![](../image/retropad/retro_b.png) | | Spacebar | ![](../image/retropad/retro_y.png) | | F2 | ![](../image/retropad/retro_select.png) | | F1 | ![](../image/retropad/retro_start.png) | | Stick Up | ![](../image/retropad/retro_dpad_up.png) | | Stick Down | ![](../image/retropad/retro_dpad_down.png) | | Stick Left | ![](../image/retropad/retro_dpad_left.png) | | Stick Right | ![](../image/retropad/retro_dpad_right.png) | | Fire A | ![](../image/retropad/retro_a.png) | | F3 | ![](../image/retropad/retro_x.png) | | F4 | ![](../image/retropad/retro_l1.png) | | F5 | ![](../image/retropad/retro_r1.png) | | Graph | ![](../image/retropad/retro_l2.png) | | Ctrl | ![](../image/retropad/retro_r2.png) | | Enter | ![](../image/retropad/retro_l3.png) | | Escape | ![](../image/retropad/retro_r3.png) | | User 1 Remap descriptors for 'Emulated Keyboard' device type | RetroPad Inputs | |--------------------------|------------------------------------------------| | Enter | ![](../image/retropad/retro_b.png) | | M | ![](../image/retropad/retro_y.png) | | F4 | ![](../image/retropad/retro_select.png) | | F1 | ![](../image/retropad/retro_start.png) | | Arrow Up | ![](../image/retropad/retro_dpad_up.png) | | Arrow Down | ![](../image/retropad/retro_dpad_down.png) | | Arrow Left | ![](../image/retropad/retro_dpad_left.png) | | Arrow Right | ![](../image/retropad/retro_dpad_right.png) | | Space | ![](../image/retropad/retro_a.png) | | N | ![](../image/retropad/retro_x.png) | | F2 | ![](../image/retropad/retro_l1.png) | | F3 | ![](../image/retropad/retro_r1.png) | | Graph | ![](../image/retropad/retro_l2.png) | | Ctrl | ![](../image/retropad/retro_r2.png) | | F5 | ![](../image/retropad/retro_l3.png) | | Escape | ![](../image/retropad/retro_r3.png) | #### Keyboard device type table | RetroKeyboard Inputs | Keyboard | |-------------------------------|--------------------| | Keyboard Backspace | Backspace | | Keyboard Tab | Tab | | Keyboard Return | Enter | | Keyboard Pause | Stop | | Keyboard Escape | Escape | | Keyboard Space | Space | | Keyboard ! | ! | | Keyboard " | " | | Keyboard # | # | | Keyboard $ | $ | | Keyboard & | & | | Keyboard ' | ` | | Keyboard ( | ( | | Keyboard ) | ) | | Keyboard * | # | | Keyboard + | + | | Keyboard , | , | | Keyboard . | . | | Keyboard / | / | | Keyboard 0 | 0 | | Keyboard 1 | 1 | | Keyboard 2 | 2 | | Keyboard 3 | 3 | | Keyboard 4 | 4 | | Keyboard 5 | 5 | | Keyboard 6 | 6 | | Keyboard 7 | 7 | | Keyboard 8 | 8 | | Keyboard 9 | 9 | | Keyboard : | : | | Keyboard ; | ; | | Keyboard - | - | | Keyboard = | = | | Keyboard < | < | | Keyboard > | > | | Keyboard ? | ? | | Keyboard @ | @ | | Keyboard [ | [ | | Keyboard \ | \ | | Keyboard ] | ] | | Keyboard ^ | ^ | | Keyboard _ | _ | | Keyboard ` | - | | Keyboard a | a | | Keyboard b | b | | Keyboard c | c | | Keyboard d | d | | Keyboard e | e | | Keyboard f | f | | Keyboard g | g | | Keyboard h | h | | Keyboard i | i | | Keyboard j | j | | Keyboard k | k | | Keyboard l | l | | Keyboard m | m | | Keyboard n | n | | Keyboard o | o | | Keyboard p | p | | Keyboard q | q | | Keyboard r | r | | Keyboard s | s | | Keyboard t | t | | Keyboard u | u | | Keyboard v | v | | Keyboard w | w | | Keyboard x | x | | Keyboard y | y | | Keyboard z | z | | Keyboard Delete | Delete | | Keyboard Numpad 0 | Numpad 0 | | Keyboard Numpad 1 | Numpad 1 | | Keyboard Numpad 2 | Numpad 2 | | Keyboard Numpad 3 | Numpad 3 | | Keyboard Numpad 4 | Numpad 4 | | Keyboard Numpad 5 | Numpad 5 | | Keyboard Numpad 6 | Numpad 6 | | Keyboard Numpad 7 | Numpad 7 | | Keyboard Numpad 8 | Numpad 8 | | Keyboard Numpad 9 | Numpad 9 | | Keyboard Up | Up | | Keyboard Down | Down | | Keyboard Right | Right | | Keyboard Left | Left | | Keyboard Insert | Insert | | Keyboard Home | Home | | Keyboard End | Select | | Keyboard Page Up | Country | | Keyboard F1 | F1 | | Keyboard F2 | F2 | | Keyboard F3 | F3 | | Keyboard F4 | F4 | | Keyboard F5 | F5 | | Keyboard Caps Lock | Caps Lock | | Keyboard Scroll Lock | Shift | | Keyboard Right Shift | Shift | | Keyboard Right Control | Control | | Keyboard Left Control | Control | | Keyboard Left Alt | Graph | ## Compatibility Awaiting description. ## External Links - [Libretro fMSX Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/fmsx_libretro.info) - [Libretro fMSX Github Repository](https://github.com/libretro/fmsx-libretro) - [Report Libretro fMSX Core Issues Here](https://github.com/libretro/fmsx-libretro/issues) - [Official fMSX Website](http://fms.komkon.org/fMSX/) - [Official fMSX Downloads](https://fms.komkon.org/fMSX/#Downloads) ### MSX - [MSX/SVI/ColecoVision/SG-1000 (blueMSX)](bluemsx.md) ================================================ FILE: docs/library/freeintv.md ================================================ # Mattel - Intellivision (FreeIntv) ## Background FreeIntv is a libretro emulation core for the Mattel Intellivision designed to be compatible with joypads from the SNES era forward even if they originally required a number pad. !!! attention FreeIntv does not currently emulate Entertainment Computer System (ECS) functionality. Contributions to the source are welcome! ### Author/License The FreeIntv core has been authored by - David Richardson The FreeIntv core is licensed under - [GPLv3](https://github.com/libretro/FreeIntv/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the FreeIntv core have the following file extensions: - .int - .rom - .bin ## Databases RetroArch database(s) that are associated with the FreeIntv core: - [Mattel - Intellivision](https://github.com/libretro/libretro-database/blob/master/rdb/Mattel%20-%20Intellivision.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:----------:|:------------------------:|:--------------------------------:| | exec.bin | Executive ROM - Required | 62e761035cb657903761800f4437b8af | | | grom.bin | Graphics ROM - Required | 0cd5946c6473e42e8e4c2137785e427f | | ## Features Frontend-level settings or features that the FreeIntv core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✕ | | Screenshots | ✔ | | Saves | ✕ | | States | ✔ | | Rewind | ✕ | | Netplay (State based) | ✕ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | Cheats (Cheats menu) | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The FreeIntv core's directory name is 'FreeIntv' ### Geometry and timing - The FreeIntv core's core provided FPS is 60 - The FreeIntv core's core provided sample rate is 44100 Hz - The FreeIntv core's core provided aspect ratio is 11/7 ## Controller overlays Mattel Intellivision games were often meant to be played with game-specific cards overlaid on the numeric keypad. These overlays convey information which can be very useful in gameplay. Images of a limited selection of Intellivision titles are available at: [http://www.intellivisionlives.com/bluesky/games/instructions.shtml](http://www.intellivisionlives.com/bluesky/games/instructions.shtml) ## Controls **Definitions:** * **Mini-Keypad** - Allows the user to view and select keys from a small Intellivision pad in the lower corner of the display. * **Controller Swap** - Some Intellivision games expect the left controller to be player one, others expect the right controller. This isn't a problem if you have two controllers (and don't mind juggling them) but users with only one controller or using a portable setup would be effectively locked out of some games. Controller Swap swaps the two controller interfaces so that the player does not have to physically swap controllers. | RetroPad | FreeIntv Function | | --- | --- | | D-Pad| 8-way movement | | Left Analog Stick | 16-way disc | | Right Analog Stick | Keypad 1-9 | | A | Right Action Button | | B | Left Action Button | | Y | Top Action Button | | X | Use the Last Selected Intellivision Keypad Button. In Astrosmash, for example, you can leave "3" selected to enable instant access to hyperspace. | | L/R | Activate the Mini-Keypad | | LT | Keypad Clear | | RT | Keypad Enter | | Left Thumb | Keypad 0 | | Right Thumb | Keypad 5 | | Start | Pause Game | | Select | Controller Swap | ## Compatibility Awaiting description. ## External Links - [Official FreeIntv Website](http://neocomputer.org/projects/freeintv/) - [Libretro FreeIntv Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/freeintv_libretro.info) - [Libretro FreeIntv Github Repository](https://github.com/libretro/FreeIntv) - [Intellivision RetroPie Wiki page](https://github.com/RetroPie/RetroPie-Setup/wiki/Intellivision) - [FreeIntv RetroPie Forums Topic](https://retropie.org.uk/forum/topic/15665/libretro-intellivision-emulator) - [FreeIntv Libretro Forums Topic](https://forums.libretro.com/t/video-demonstration-of-the-new-freeintv-intellivision-core/14389) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0Ie3IvIC1OLrsG-9qJ-RbP7r) ================================================ FILE: docs/library/fuse.md ================================================ # ZX Spectrum (Fuse) ## Background The Free Unix Spectrum Emulator (Fuse): an emulator of the 1980s home computer and various clones for Unix, Mac OS X and Windows. The Fuse core has been authored by - Team Fuse The Fuse core is licensed under - [GPLv3](https://github.com/libretro/fuse-libretro/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Required or optional firmware files go in the frontend's system directory. !!! attention The BIOS for the last four machines need to be in a directory named 'fuse' in RetroArch's System directory. - Spectrum 48K - Spectrum 48K (NTSC) - Spectrum 128K - Spectrum +2 - Spectrum +2A - Spectrum +3 - Spectrum +3e - Spectrum SE - Timex TC2048 - Timex TC2068 - Timex TS2068 - Spectrum 16K - Pentagon 128K | Filename | Description | md5sum | |:---------------:|:----------------------------:|:--------------------------------:| | fuse/128p-0.rom | Pentagon 128K ROM - Required | | | fuse/128p-1.rom | Pentagon 128K ROM - Required | | | fuse/trdos.rom | Pentagon 128K ROM - Required | | - Pentagon 512K | Filename | Description | md5sum | |:---------------:|:----------------------------:|:--------------------------------:| | fuse/128p-0.rom | Pentagon 512K ROM - Required | | | fuse/128p-1.rom | Pentagon 512K ROM - Required | | | fuse/gluck.rom | Pentagon 512K ROM - Required | | | fuse/trdos.rom | Pentagon 512K ROM - Required | | - Pentagon 1024 | Filename | Description | md5sum | |:---------------:|:----------------------------:|:--------------------------------:| | fuse/128p-0.rom | Pentagon 1024 ROM - Required | | | fuse/128p-1.rom | Pentagon 1024 ROM - Required | | | fuse/gluck.rom | Pentagon 1024 ROM - Required | | | fuse/trdos.rom | Pentagon 1024 ROM - Required | | - Scorpion 256K | Filename | Description | md5sum | |:---------------:|:----------------------------:|:--------------------------------:| | fuse/256s-0.rom | Scorpion 256K ROM - Required | | | fuse/256s-1.rom | Scorpion 256K ROM - Required | | | fuse/256s-2.rom | Scorpion 256K ROM - Required | | | fuse/256s-3.rom | Scorpion 256K ROM - Required | | ## Extensions Content that can be loaded by the Fuse core have the following file extensions: - .tzx - .tap - .z80 - .rzx - .scl - .trd RetroArch database(s) that are associated with the Fuse core: - [Sinclair - ZX Spectrum +3](https://github.com/libretro/libretro-database/blob/master/rdb/Sinclair%20-%20ZX%20Spectrum%20%2B3.rdb) - [Sinclair - ZX Spectrum](https://github.com/libretro/libretro-database/blob/master/rdb/Sinclair%20-%20ZX%20Spectrum.rdb) ## Features Frontend-level settings or features that the Fuse core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✕ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Fuse core's library name is 'fuse' The Fuse core saves/loads to/from these directories. **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ### Geometry and timing - The Fuse core's core provided FPS is (FPS) - The Fuse core's core provided sample rate is 44100 Hz - The Fuse core's base width is (Base width) - The Fuse core's base height is (Base height) - The Fuse core's max width is (Max width) - The Fuse core's max height is (Max height) - The Fuse core's core provided aspect ratio is (Ratio) ## Games There are hundreds of free, legally available ZX Spectrum games at [World of Spectrum](http://www.worldofspectrum.org/). You should start at the [Visitor Voted Top 100 Best Games](http://www.worldofspectrum.org/bestgames.html). ## Core options The Fuse core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Model (needs content load)** [fuse_machine] (**Spectrum 48K**|Spectrum 48K (NTSC)|Spectrum 128K|Spectrum +2|Spectrum +2A|Spectrum +3|Spectrum +3e|Spectrum SE|Timex TC2048|Timex TC2068|Timex TS2068|Spectrum 16K|Pentagon 128K|Pentagon 512K|Pentagon 1024|Scorpion 256K) Set the machine to emulate. Note that the this setting will have effect only when a new content is loaded. - **Hide Video Border** [fuse_hide_border] (**Off**|On) Hides the video border, making the game occupy the entire screen area. - **Tape Fast Load** [fuse_fast_load] (Off|**On**) Instantly loads tape files if enabled, or disabled it to see the moving horizontal lines in the video border while the game loads. - **Tape Load Sound** [fuse_load_sound] (Off|**On**) Outputs the tape sound if fast load is disabled. - **Speaker Type** [fuse_speaker_type] (**tv speaker**|beeper|unfiltered) Applies an audio filter. - **AV Stereo Separation** [fise_ay_stereo_separation] (**none**|acb|abc) The AY sound chip stereo separation. - **Transparent Keyboard Overlay** [fuse_key_ovrlay_transp] (Off|**On**) If the keyboard overlay is transparent or opaque. - **Time to Release Key in ms** [fuse_key_hold_time] (**500**|1000|100|300) How much time to keep a key pressed before releasing it (used when a key is pressed using the keyboard overlay). - **Joy Left mapping** [fuse_joypad_left] (****|0|1|2|3|4|5|6|7|8|9|a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z|Enter|Caps|Symbol|Space) Map the Left joypad input to a keyboard input. - **Joy Right mapping** [fuse_joypad_right] (****|0|1|2|3|4|5|6|7|8|9|a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z|Enter|Caps|Symbol|Space) Map the Right joypad input to a keyboard input. - **Joy Up mapping** [fuse_joypad_up] (****|0|1|2|3|4|5|6|7|8|9|a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z|Enter|Caps|Symbol|Space) Map the Up joypad input to a keyboard input. - **Joy Down mapping** [fuse_joypad_down] (****|0|1|2|3|4|5|6|7|8|9|a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z|Enter|Caps|Symbol|Space) Map the Down joypad input to a keyboard input. - **Joy Start mapping** [fuse_joypad_start] (****|0|1|2|3|4|5|6|7|8|9|a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z|Enter|Caps|Symbol|Space) Map the Start joypad input to a keyboard input. - **Joy A mapping** [fuse_joypad_a] (****|0|1|2|3|4|5|6|7|8|9|a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z|Enter|Caps|Symbol|Space) Map the A joypad input to a keyboard input. - **Joy B mapping** [fuse_joypad_b] (****|0|1|2|3|4|5|6|7|8|9|a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z|Enter|Caps|Symbol|Space) Map the B joypad input to a keyboard input. - **Joy X mapping** [fuse_joypad_x] (****|0|1|2|3|4|5|6|7|8|9|a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z|Enter|Caps|Symbol|Space) Map the X joypad input to a keyboard input. - **Joy Y mapping** [fuse_joypad_y] (****|0|1|2|3|4|5|6|7|8|9|a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z|Enter|Caps|Symbol|Space) Map the Y joypad input to a keyboard input. - **Joy L mapping** [fuse_joypad_l] (****|0|1|2|3|4|5|6|7|8|9|a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z|Enter|Caps|Symbol|Space) Map the L joypad input to a keyboard input. - **Joy R mapping** [fuse_joypad_r] (****|0|1|2|3|4|5|6|7|8|9|a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z|Enter|Caps|Symbol|Space) Map the R joypad input to a keyboard input. - **Joy L2 mapping** [fuse_joypad_l2] (****|0|1|2|3|4|5|6|7|8|9|a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z|Enter|Caps|Symbol|Space) Map the L2 joypad input to a keyboard input. - **Joy R2 mapping** [fuse_joypad_r2] (****|0|1|2|3|4|5|6|7|8|9|a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z|Enter|Caps|Symbol|Space) Map the R2 joypad input to a keyboard input. - **Joy L3 mapping** [fuse_joypad_l3] (****|0|1|2|3|4|5|6|7|8|9|a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z|Enter|Caps|Symbol|Space) Map the L3 joypad input to a keyboard input. - **Joy R3 mapping** [fuse_joypad_r3] (****|0|1|2|3|4|5|6|7|8|9|a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z|Enter|Caps|Symbol|Space) Map the R3 joypad input to a keyboard input. ## Controllers usage There are seven types of joysticks emulated: 1. Cursor 2. Kempston 3. Sinclair 1 4. Sinclair 2 5. Timex 1 6. Timex 2 7. Fuller Joystick Users can configure their joystick types in the input configuration on the front end. However, fuse-libretro allows for two joysticks at maximum so only users one and two can actually use theirs in the emulation. Users 1 and 2 can choose any of the joysticks as their device types, user 3 can only choose the Sinclair Keyboard. Buttons A, X and Y are mapped to the joystick's fire button, and button B is mapped to the UP directional button. Buttons L1 and R1 are mapped to RETURN and SPACE, respectively. The SELECT button brings up the embedded, on-screen keyboard which is useful if you only have controllers attached to your box. There are some conflicts in the way the input devices interact because of the use of the physical keyboard keys as joystick buttons. For a good gaming experience, set the user device types as follows: - For joystick games: Set user 1 to a joystick type. Optionally, set user 2 to another joystick type (local cooperative games). Set user 3 to none. This way, you can use L1 as RETURN, R1 as SPACE, and SELECT to bring the embedded keyboard. - For keyboard games: Set users 1 and 2 to none, and user 3 to Sinclair Keyboard. You won't have any joystick and the embedded keyboard won't work, but the entire physical keyboard will be available for you to type in those text adventure commands. If you set a joystick along with the keyboard, the joystick will work just fine except for the bindings to RETURN and SPACE, and the keyboard won't register the keys assigned to the Cursor joystick, or to the L1 and R1 buttons for all other joystick types. ### Device types The Fuse core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): #### User 1 - 2 device types - None - Input disabled. - **RetroPad** - Joypad - Cursor Joystick - Joypad - Kempston Joystick - Joypad - Sinclair 1 Joystick - Joypad - Sinclair 2 Joystick - Joypad - Timex 1 Joystick - Joypad - Timex 2 Joystick - Joypad - Fuller Joystick - Joypad #### User 3 device types - None - Input disabled. - **RetroPad** - Joypad - Sinclair Keyboard - Keyboard - Has keymapper support ### Joypad | User 1 - 7 input descriptors | RetroPad Inputs | |------------------------------|---------------------------------------------| | Up | ![](../image/retropad/retro_b.png) | | Fire | ![](../image/retropad/retro_y.png) | | Keyboard overlay | ![](../image/retropad/retro_select.png) | | Up | ![](../image/retropad/retro_dpad_up.png) | | Down | ![](../image/retropad/retro_dpad_down.png) | | Left | ![](../image/retropad/retro_dpad_left.png) | | Right | ![](../image/retropad/retro_dpad_right.png) | | Fire | ![](../image/retropad/retro_a.png) | | Fire | ![](../image/retropad/retro_x.png) | | Enter | ![](../image/retropad/retro_l1.png) | | Space | ![](../image/retropad/retro_r1.png) | ### Keyboard | RetroKeyboard Inputs | Sinclair Keyboard | |-------------------------------|--------------------| | Keyboard Backspace | Backspace | | Keyboard Return | Return | | Keyboard Space | Space | | Keyboard 0 | 0 | | Keyboard 1 | 1 | | Keyboard 2 | 2 | | Keyboard 3 | 3 | | Keyboard 4 | 4 | | Keyboard 5 | 5 | | Keyboard 6 | 6 | | Keyboard 7 | 7 | | Keyboard 8 | 8 | | Keyboard 9 | 9 | | Keyboard a | a | | Keyboard b | b | | Keyboard c | c | | Keyboard d | d | | Keyboard e | e | | Keyboard f | f | | Keyboard g | g | | Keyboard h | h | | Keyboard i | i | | Keyboard j | j | | Keyboard k | k | | Keyboard l | l | | Keyboard m | m | | Keyboard n | n | | Keyboard o | o | | Keyboard p | p | | Keyboard q | q | | Keyboard r | r | | Keyboard s | s | | Keyboard t | t | | Keyboard u | u | | Keyboard v | v | | Keyboard w | w | | Keyboard x | x | | Keyboard y | y | | Keyboard z | z | | Keyboard Right Shift | Right Shift | | Keyboard Left Shift | Left Shift | | Keyboard Right Control | Right Control | | Keyboard Left Control | Left Control | | Keyboard Right Alt | Right Alt | | Keyboard Left Alt | Left Alt | | Keyboard Right Meta | Right Meta | | Keyboard Left Meta | Left Meta | | Keyboard Right Super | Right Super | | Keyboard Left Super | Left Super | ## External Links - [Official Fuse Website](http://fuse-emulator.sourceforge.net/) - [Official Fuse SourceForge Repository](https://sourceforge.net/projects/fuse-emulator/) - [Libretro Fuse Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/fuse_libretro.info) - [Libretro Fuse Github Repository](https://github.com/libretro/fuse-libretro) - [Report Libretro Fuse Core Issues Here](https://github.com/libretro/fuse-libretro/issues) ================================================ FILE: docs/library/gam4980.md ================================================ # GAM4980 ## Background GAM4980 is a libretro core for playing BBK Longman 4980 electronic dictionary games. The GAM4980 core has been authored by: - [无云](https://gitee.com/BA4988/BBK-simulator) - [iyzsong](https://codeberg.org/iyzsong) The GAM4980 core is licensed under: - [GPLv3+](https://codeberg.org/iyzsong/gam4980/raw/branch/master/COPYING) ## BIOS [Required firmware files](https://docs.libretro.com/library/bios/) go in the frontend's system directory: | Filename | Description | |:-----------------:|:-----------------------------------------:| | gam4980/8.BIN | font rom, dumped from 0x800000-0x9fffff | | gam4980/E.BIN | system rom, dumped from 0xe00000-0xffffff | You need run a rom [dumper](https://codeberg.org/iyzsong/ba4980-c-sdk/releases/download/固件导出/固件导出.gam) on BBK4980 (or 4988/5980) and a XMODEM1K terminal on PC to get the firmware files. ## Extensions Content that can be loaded by the GAM4980 core have the following file extensions: - .gam ## Features Frontend-level settings or features that the [Core name] core respects: | Feature | Supported | |-------------------|:---------:| | Restart | ✕ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | - | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | - | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Geometry and timing - The [Core name] core's core provided FPS is 60.0 - The [Core name] core's base width is 159 - The [Core name] core's base height is 96 - The [Core name] core's max width is 159 - The [Core name] core's max height is 96 - The [Core name] core's core provided aspect ratio is 5/3 ## User 1 device types The GAM4980 core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ## Joypad | RetroPad Inputs | User # input descriptors | |------------------------------------------------|--------------------------| | ![](../image/retropad/retro_b.png) | Exit | | ![](../image/retropad/retro_y.png) | Help (4988: Z) | | ![](../image/retropad/retro_select.png) | Insert (4988: Shift) | | ![](../image/retropad/retro_start.png) | Search (4988: ZY) | | ![](../image/retropad/retro_dpad_up.png) | Up | | ![](../image/retropad/retro_dpad_down.png) | Down | | ![](../image/retropad/retro_dpad_left.png) | Left | | ![](../image/retropad/retro_dpad_right.png) | Right | | ![](../image/retropad/retro_a.png) | Enter | | ![](../image/retropad/retro_x.png) | R | | ![](../image/retropad/retro_l1.png) | Page Up | | ![](../image/retropad/retro_r1.png) | Page Down | | ![](../image/retropad/retro_l2.png) | Modify (4988: Space) | | ![](../image/retropad/retro_r2.png) | Del (4988: X) | | ![](../image/retropad/retro_l3.png) | A | | ![](../image/retropad/retro_r3.png) | Z (4988: S) | ================================================ FILE: docs/library/gambatte.md ================================================ # Nintendo - Game Boy / Color (Gambatte) ## Background Gambatte is an accuracy-focused, open-source, cross-platform Game Boy Color emulator written in C++. It is based on hundreds of corner case hardware tests, as well as previous documentation and reverse engineering efforts. The Gambatte core has been authored by - Sinamas The Gambatte core is licensed under - [GPLv2](https://github.com/libretro/gambatte-libretro/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Required or optional firmware files go in the frontend's system directory. !!! attention The ['Use official bootloader' core option](#core-options) must be set to On in order for these BIOS files to be used. | Filename | Description | md5sum | |:------------:|:------------------------------:|:--------------------------------:| | gb_bios.bin | Game Boy BIOS - Optional | 32fbbd84168d3482956eb3c5051637f5 | | gbc_bios.bin | Game Boy Color BIOS - Optional | dbfce9db9deaa2567f6a84fde55f9680 | ## Extensions Content that can be loaded by the Gambatte core have the following file extensions: - .gb - .gbc - .dmg RetroArch database(s) that are associated with the Gambatte core: - [Nintendo - Game Boy](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Game%20Boy.rdb) - [Nintendo - Game Boy Color](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Game%20Boy%20Color.rdb) ## Features Frontend-level settings or features that the Gambatte core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✔ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Directories The Gambatte core's library name is 'Gambatte' The Gambatte core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:----------------------:| | *.srm | Cartridge battery save | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ***Frontend's System directory** | File | Description | |:---------------------------:|:-----------------------:| | palettes/default.pal | Global custom palette | | palettes/'content-name'.pal | Per-game custom palette | ## Geometry and timing - The Gambatte core's core provided FPS is 59.7275005696 - The Gambatte core's core provided sample rate is [Sample rate] - The Gambatte core's base width is [Base width] - The Gambatte core's base height is [Base height] - The Gambatte core's max width is [Max width] - The Gambatte core's max height is [Max height] - The Gambatte core's core provided aspect ratio is [Aspect ratio] ## Color Palette ![screen_record__2021_10_06__17_11_02](https://user-images.githubusercontent.com/38211560/136244454-945e0b6e-070f-4947-8067-22f971d00223.gif) - The [core option](#core-options) `GB Colorization` enables colorization of Game Boy games, using pre-defined or user-selected color palettes. - When satisfied you can save the currently chosen palette per the whole core, per content-directory or per game with the usual RetroArch [override](../guides/overrides.md) mechanism. - During gameplay you can instantly swap color palettes. - You can cycle through the available color palettes with the [L/R shoulder buttons](#joypad). (Source: Feature request in issue [182](https://github.com/libretro/gambatte-libretro/issues/182) was implemented in pull request [204](https://github.com/libretro/gambatte-libretro/pull/204) in October 2021) - This is ideal for your initial browsing / exploration of the color palettes. - But also if you spontanously want to change the palette in your currently running game. ### Custom palettes for Game Boy games The 'GB Colorization' core option must be set to custom. Create a folder called "palettes" in RetroArch's system directory. Then, you can place custom palette files (.pal) inside the "palettes" folder You can define different palettes for specific games by creating a .pal file in the "palettes" folder with 'INTERNALROMNAME.pal' or "rom-name.pal". If no specific palette is found for a ROM then the default palette is used. You can also define a palette to be used for all Game Boy games by creating a .pal file in the "palettes" folder named "default.pal" ??? note "*Custom palettes can be created from the GUI in standalone Gambatte*" ![](../image/core/gambatte/tool.png) ## Core options The Gambatte core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Allow Opposing Directions** [gambatte_up_down_allowed] (**disabled**/enabled) Enabling this will allow pressing / quickly alternating / holding both left and right (or up and down in some games) directions at the same time. This may cause movement based glitches to occur in certain games. It's best to keep this core option disabled. - **GB Colorization** [gambatte_gb_colorization] (**disabled**|auto|GBC|SGB|internal|custom) Enables colorization of Game Boy games, using pre-defined or user-selected color palettes. 'auto': Selects automatically the 'best' (most colorful/appropriate) palette for each individual game, using the following order of preference: 1. Game-specific Super Game Boy palette, if defined and more colorful than game-specific Game Boy Color palette. 2. Game-specific Game Boy Color palette, if defined. 3. Game-specific Super Game Boy palette, if defined. 4. Palette specified by 'Internal Palette' core option. 'GBC': Selects game-specific Game Boy Color palette, if defined. If not, falls back to the Game Boy Color hardware default palette of 'GBC - Dark Green'. 'SGB': Selects game-specific Super Game Boy palette, if defined. If not, falls back to the Super Game Boy hardware default palette of 'SGB - 1A'. 'internal': Selects palette specified by 'Internal Palette' core option. 'custom': Loads user-created palettes from RetroArch's system directory, as described in the 'Custom palettes for Game Boy games' section. ??? note "*GB Colorization: Off*" ![](../image/core/gambatte/color_off.png) ??? note "*GB Colorization: auto (in this case, a game-specific SGB palette is auto-selected)*" ![](../image/core/gambatte/color_auto.png) ??? note "*GB Colorization: GBC*" ![](../image/core/gambatte/color_gbc.png) - **Internal Palette** [gambatte_gb_internal_palette] (**GB - DMG**|GB - Pocket|GB - Light|GBC - Blue|GBC - Brown|GBC - Dark Blue|GBC - Dark Brown|GBC - Dark Green|GBC - Grayscale|GBC - Green|GBC - Inverted|GBC - Orange|GBC - Pastel Mix|GBC - Red|GBC - Yellow|SGB - 1A|SGB - 1B|SGB - 1C|SGB - 1D|SGB - 1E|SGB - 1F|SGB - 1G|SGB - 1H|SGB - 2A|SGB - 2B|SGB - 2C|SGB - 2D|SGB - 2E|SGB - 2F|SGB - 2G|SGB - 2H|SGB - 3A|SGB - 3B|SGB - 3C|SGB - 3D|SGB - 3E|SGB - 3F|SGB - 3G|SGB - 3H|SGB - 4A|SGB - 4B|SGB - 4C|SGB - 4D|SGB - 4E|SGB - 4F|SGB - 4G|SGB - 4H|Special 1|Special 2|Special 3) Selects the internal color palette to use for colorizing Game Boy games when the 'GB Colorization' core option is set to 'internal', or when the 'GB Colorization' core option is set to 'auto' and a game has no pre-defined Super Game Boy/Game Boy Color palette. 'GB' palettes mimic the display characteristics of original Game Boy hardware. 'GBC' palettes are identical to those used by original Game Boy Color hardware when colorizing Game Boy games. 'SGB' palettes are identical to those used by original Super Game Boy hardware when colorizing Game Boy games. ??? note "*Internal Palette: GB - DMG*" ![](../image/core/gambatte/gb_dmg.png) ??? note "*Internal Palette: GB - Pocket*" ![](../image/core/gambatte/gb_pocket.png) ??? note "*Internal Palette: GB - Light*" ![](../image/core/gambatte/gb_light.png) ??? note "*Internal Palette: GBC - Blue*" ![](../image/core/gambatte/gbc_blue.png) ??? note "*Internal Palette: GBC - Brown*" ![](../image/core/gambatte/gbc_brown.png) ??? note "*Internal Palette: GBC - Dark Blue*" ![](../image/core/gambatte/gbc_dark_blue.png) ??? note "*Internal Palette: GBC - Dark Brown*" ![](../image/core/gambatte/gbc_dark_brown.png) ??? note "*Internal Palette: GBC - Dark Green*" ![](../image/core/gambatte/gbc_dark_green.png) ??? note "*Internal Palette: GBC - Grayscale*" ![](../image/core/gambatte/gbc_grayscale.png) ??? note "*Internal Palette: GBC - Green*" ![](../image/core/gambatte/gbc_green.png) ??? note "*Internal Palette: GBC - Inverted*" ![](../image/core/gambatte/gbc_inverted.png) ??? note "*Internal Palette: GBC - Orange*" ![](../image/core/gambatte/gbc_orange.png) ??? note "*Internal Palette: GBC - Pastel Mix*" ![](../image/core/gambatte/gbc_pastel.png) ??? note "*Internal Palette: GBC - Red*" ![](../image/core/gambatte/gbc_red.png) ??? note "*Internal Palette: GBC - Yellow*" ![](../image/core/gambatte/gbc_yellow.png) ??? note "*Internal Palette: SGB - 1A*" ![](../image/core/gambatte/sgb_1a.png) ??? note "*Internal Palette: SGB - 1B*" ![](../image/core/gambatte/sgb_1b.png) ??? note "*Internal Palette: SGB - 1C*" ![](../image/core/gambatte/sgb_1c.png) ??? note "*Internal Palette: SGB - 1D*" ![](../image/core/gambatte/sgb_1d.png) ??? note "*Internal Palette: SGB - 1E*" ![](../image/core/gambatte/sgb_1e.png) ??? note "*Internal Palette: SGB - 1F*" ![](../image/core/gambatte/sgb_1f.png) ??? note "*Internal Palette: SGB - 1G*" ![](../image/core/gambatte/sgb_1g.png) ??? note "*Internal Palette: SGB - 1H*" ![](../image/core/gambatte/sgb_1h.png) ??? note "*Internal Palette: SGB - 2A*" ![](../image/core/gambatte/sgb_2a.png) ??? note "*Internal Palette: SGB - 2B*" ![](../image/core/gambatte/sgb_2b.png) ??? note "*Internal Palette: SGB - 2C*" ![](../image/core/gambatte/sgb_2c.png) ??? note "*Internal Palette: SGB - 2D*" ![](../image/core/gambatte/sgb_2d.png) ??? note "*Internal Palette: SGB - 2E*" ![](../image/core/gambatte/sgb_2e.png) ??? note "*Internal Palette: SGB - 2F*" ![](../image/core/gambatte/sgb_2f.png) ??? note "*Internal Palette: SGB - 2G*" ![](../image/core/gambatte/sgb_2g.png) ??? note "*Internal Palette: SGB - 2H*" ![](../image/core/gambatte/sgb_2h.png) ??? note "*Internal Palette: SGB - 3A*" ![](../image/core/gambatte/sgb_3a.png) ??? note "*Internal Palette: SGB - 3B*" ![](../image/core/gambatte/sgb_3b.png) ??? note "*Internal Palette: SGB - 3C*" ![](../image/core/gambatte/sgb_3c.png) ??? note "*Internal Palette: SGB - 3D*" ![](../image/core/gambatte/sgb_3d.png) ??? note "*Internal Palette: SGB - 3E*" ![](../image/core/gambatte/sgb_3e.png) ??? note "*Internal Palette: SGB - 3F*" ![](../image/core/gambatte/sgb_3f.png) ??? note "*Internal Palette: SGB - 3G*" ![](../image/core/gambatte/sgb_3g.png) ??? note "*Internal Palette: SGB - 3H*" ![](../image/core/gambatte/sgb_3h.png) ??? note "*Internal Palette: SGB - 4A*" ![](../image/core/gambatte/sgb_4a.png) ??? note "*Internal Palette: SGB - 4B*" ![](../image/core/gambatte/sgb_4b.png) ??? note "*Internal Palette: SGB - 4C*" ![](../image/core/gambatte/sgb_4c.png) ??? note "*Internal Palette: SGB - 4D*" ![](../image/core/gambatte/sgb_4d.png) ??? note "*Internal Palette: SGB - 4E*" ![](../image/core/gambatte/sgb_4e.png) ??? note "*Internal Palette: SGB - 4F*" ![](../image/core/gambatte/sgb_4f.png) ??? note "*Internal Palette: SGB - 4G*" ![](../image/core/gambatte/sgb_4g.png) ??? note "*Internal Palette: SGB - 4H*" ![](../image/core/gambatte/sgb_4h.png) ??? note "*Internal Palette: Special 1*" ![](../image/core/gambatte/special1.png) ??? note "*Internal Palette: Special 2*" ![](../image/core/gambatte/special2.png) ??? note "*Internal Palette: Special 3*" ![](../image/core/gambatte/special3.png) - **Color correction** [gambatte_gbc_color_correction] (**GBC only**|always|disabled) Enables adjustment of output colors to match the display characteristics of the LCD panel used in original Game Boy Color hardware. 'GBC only': Color correction is only applied when playing Game Boy Color games, or when using a Game Boy Color palette to colorize a Game Boy game. 'always': Color correction is always applied, regardless of which color palette is being used. !!! attention Setting this option to 'always' will result in unexpected/suboptimal output when using 'GB' or 'SGB' internal color palettes, since these are intended for display on a normal TV/monitor rather than a Game Boy Color LCD panel. - **Color correction mode** [gambatte_gbc_color_correction_mode] (**accurate**|fast) Specifies the method to use when performing color correction. 'accurate': Provides a very close approximation of the image displayed on a real Game Boy Color LCD panel. 'fast': Darkens colors in a loose approximation of the image displayed on a real Game Boy Color LCD panel. Has negligible performance impact, and may be used on low-end hardware in cases where the 'accurate' method is too slow. ??? note "*Color correction: Off*" ![](../image/core/gambatte/correct_off.png) ??? note "*Color correction: fast*" ![](../image/core/gambatte/correct_fast.png) ??? note "*Color correction: accurate*" ![](../image/core/gambatte/correct_accurate.png) - **Color correction - frontlight position** [gambatte_gbc_frontlight_position] (**central**|above screen|below screen) Simulates the physical response of the Game Boy Color LCD panel when illuminated from different angles. 'central': Standard color reproduction, corresponding to ambient light hitting the screen at 90°. 'above screen': Increases brightness (gamma), corresponding to sunlight or a ceiling light shining on the screen from above. 'below screen': Reduces brightness (gamma), corresponding to light shining on the screen from below. !!! attention This setting only takes effect when 'Color correction mode' is set to 'accurate'. ??? note "*Color correction - frontlight position: central*" ![](../image/core/gambatte/frontlight_central.png) ??? note "*Color correction - frontlight position: above screen*" ![](../image/core/gambatte/frontlight_above_screen.png) ??? note "*Color correction - frontlight position: below screen*" ![](../image/core/gambatte/frontlight_below_screen.png) - **Dark Filter Level (percent)** [gambatte_dark_filter_level] (**0**|5|10|15|20|25|30|35|40|45|50) Enables selective brightness reduction based upon pixel luminosity. May be used to reduce glare/eye strain. Of particular value when playing games with white backgrounds, which are intended for display on a non-backlit Game Boy Color LCD panel and appear uncomfortably bright when viewed on a modern backlit screen. ??? note "*Dark Filter Level: 0%*" ![](../image/core/gambatte/dark_filter_off.png) ??? note "*Dark Filter Level: 30%*" ![](../image/core/gambatte/dark_filter_30.png) - **Emulated hardware (restart)** [gambatte_gb_hwmode] (**Auto**|GB|GBC|GBA) Choose which hardware is emulated Game Boy, Game Boy Color, or Game Boy Advance. - **Use official bootloader (restart)** [gambatte_gb_bootloader] (**enabled**|disabled) Enables support for using official Game Boy and Game Boy Color bootloaders with startup logos. Check the [BIOS section](#bios) to see what files are needed. ??? note "*Game Boy bootloader*" ![](../image/core/gambatte/gb_bios.png) ??? note "*Game Boy Color bootloader*" ![](../image/core/gambatte/gbc_bios.png) - **Mix frames** [gambatte_mix_frames] (**disabled**|accurate|fast) Enables simulation of LCD ghosting effects by blending the current and previous frames. 'accurate': Blends pixel RGB values with floating point precision. 'fast': Blends pixel RGB values using fast bit manipulation. Causes slight color darkening/shifting (due to rounding errors). May be used on low-end hardware in cases where the 'accurate' method is too slow. !!! attention A number of games generate transparency effects (or additional shades of color) by drawing objects on alternate frames, relying on the LCD ghosting of original hardware to 'smooth out' the result. Notable examples are Wave Race, Ballistic and Chikyuu Kaihou Gun ZAS. In order for these games to render correctly, 'Mix frames' must be set to 'accurate' or 'fast'. More importantly, the rapid flickering that is produced by these games when 'Mix frames' is disabled can lead to a form of screen burn-in on certain types of LCD panel (that of the 3DS in particular). ??? note "*Mix frames: Off*" ![](../image/core/gambatte/mix_frames_off.gif) ??? note "*Mix frames: accurate*" ![](../image/core/gambatte/mix_frames_accurate.gif) ??? note "*Mix frames: fast*" ![](../image/core/gambatte/mix_frames_fast.gif) - **GameBoy Link Mode** - New config options | Core Option | Description | |---------------------------------------------------|-----------------------------------------------------------| | gambatte_gb_link_mode | **Not Connected** / Network Server / Network Client | | gambatte_gb_link_network_port | 56400 to 56420 in increments of 1. **56400 is default** | | gambatte_show_gb_link_settings | enabled / **disabled** | | gambatte_gb_link_network_server_ip_1 | (client only) 0 to 9, 1st digit of ipv4 address, (eg. 1) | | gambatte_gb_link_network_server_ip_2 | (client only) 0 to 9, 2nd digit of ipv4 address, (eg. 9) | | gambatte_gb_link_network_server_ip_3 | (client only) 0 to 9, 3rd digit of ipv4 address, (eg. 2) | | gambatte_gb_link_network_server_ip_4 | (client only) 0 to 9, 4th digit of ipv4 address, (eg. 1) | | gambatte_gb_link_network_server_ip_5 | (client only) 0 to 9, 5th digit of ipv4 address, (eg. 6) | | gambatte_gb_link_network_server_ip_6 | (client only) 0 to 9, 6th digit of ipv4 address, (eg. 8) | | gambatte_gb_link_network_server_ip_7 | (client only) 0 to 9, 7th digit of ipv4 address, (eg. 0) | | gambatte_gb_link_network_server_ip_8 | (client only) 0 to 9, 8th digit of ipv4 address, (eg. 0) | | gambatte_gb_link_network_server_ip_9 | (client only) 0 to 9, 9th digit of ipv4 address, (eg. 1) | | gambatte_gb_link_network_server_ip_10 | (client only) 0 to 9, 10th digit of ipv4 address, (eg. 0) | | gambatte_gb_link_network_server_ip_11 | (client only) 0 to 9, 11th digit of ipv4 address, (eg. 0) | | gambatte_gb_link_network_server_ip_12 | (client only) 0 to 9, 12th digit of ipv4 address, (eg. 1) | - **GameBoy Link Mode** - Old config options | Core Option | Description, values |----------------------------------------------|-----------------------------------------------------------------------------------------------------| | gambatte_gb_link_mode | Mode, **Not Connected** / Network Server / Network Client | | gambatte_gb_link_network_port | Network link port, 56400 to 56420 in increments of 1. **56400 is default** | | gambatte_gb_link_network_server_ip_octet1 | (client only) Network link server address part 1, (0 to 255 in increments of 1. **0 is default**.) | | gambatte_gb_link_network_server_ip_octet2 | (client only) Network link server address part 2, (0 to 255 in increments of 1. **0 is default**.) | | gambatte_gb_link_network_server_ip_octet3 | (client only) Network link server address part 3, (0 to 255 in increments of 1. **0 is default**.) | | gambatte_gb_link_network_server_ip_octet4 | (client only) Network link server address part 4, (0 to 255 in increments of 1. **0 is default**.) | ## Rumble Rumble only works in the mGBA core when - The content being ran has rumble support. (e.g. Cartridges with a Rumble Pak) - The frontend being used has rumble support. - The joypad device being used has rumble support. ## Joypad ![](../image/controller/gb.png) | RetroPad Inputs | User 1 input descriptors | |------------------------------------------------|-------------------------------------------| | ![](../image/retropad/retro_a.png) | A | | ![](../image/retropad/retro_b.png) | B | | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | | ![](../image/retropad/retro_select.png) | Select | | ![](../image/retropad/retro_start.png) | Start | | ![](../image/retropad/retro_l1.png) | Previous [Color Palette](#color-palette) | | ![](../image/retropad/retro_r1.png) | Next [Color Palette](#color-palette) | ## Compatibility | Game | Issue | |---------------------------------------------------|----------------------------------------------------| | Command Master | Crashes on start. Unemulated MBC7 mapper. | | Game Boy Camera | Crashes on start. Unemulated Pocket Camera mapper. | | Game de Hakken!! Tamagotchi - Osutchi to Mesutchi | Crashes on start. Unemulated TAMA5 mapper. | | Kirby Tilt 'n' Tumble | Crashes on start. Unemulated MBC7 mapper. | | Net de Get: Mini-Game @ 100 | Crashes on start. Unemulated MBC6 mapper. | ## External Links - [Official Gambatte Github Repository](https://github.com/sinamas/gambatte) - [Old Standalone Gambatte builds](https://sourceforge.net/projects/gambatte/files/gambatte/) - [Libretro Gambatte Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/gambatte_libretro.info) - [Libretro Gambatte Github Repository](https://github.com/libretro/gambatte-libretro) - [Report Libretro Gambatte Core Issues Here](https://github.com/libretro/gambatte-libretro/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0IdJ4pq_2h9d8Q0QO7FA7Ukd) ## Nintendo - Game Boy (+ Color) - [Nintendo - Game Boy / Color (Emux GB)](emux_gb.md) - [Nintendo - Game Boy / Color (Gearboy)](gearboy.md) - [Nintendo - Game Boy / Color (SameBoy)](sameboy.md) - [Nintendo - Game Boy / Color (TGB Dual)](tgb_dual.md) - [Nintendo - Game Boy Advance (mGBA)](mgba.md) - [Nintendo - Game Boy Advance (VBA-M)](vba_m.md) - [Nintendo - SNES / Famicom (higan Accuracy)](higan_accuracy.md) - [Nintendo - SNES / Famicom (nSide Balanced)](nside_balanced.md) - [Nintendo - SNES / Famicom (Mesen-S)](mesen-s.md) ================================================ FILE: docs/library/game_music_emu.md ================================================ # Game Music Emu ## Background Multi-purpose video game console music player. ### Author/License The Game Music Emu core has been authored by - Blargg The Game Music Emu core is licensed under - [GPLv3](https://github.com/libretro/libretro-gme/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Game Music Emu core have the following file extensions: - .ay - .gbs - .gym - .hes - .kss - .nsf - .nsfe - .sap - .spc - .vgm - .vgz ## Features Frontend-level settings or features that the Game Music Emu core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✕ | | Screenshots | ✔ | | Saves | ✕ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✕ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Game Music Emu core's internal core name is 'Game Music Emulator' ### Geometry and timing - The Game Music Emu core's core provided FPS is 60 - The Game Music Emu core's core provided sample rate is 44100 Hz - The Game Music Emu core's core provided aspect ratio is 4/3 ## Controllers The Game Music Emu core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. - **RetroPad** - Joypad - Stay on this. - RetroPad w/Analog - Joypad - There's no reason to switch to this. ### Controller tables #### Joypad | RetroPad Inputs | Game Music Emu core inputs | |------------------------------------------------|----------------------------| | ![](../image/retropad/retro_start.png) | Pause | | ![](../image/retropad/retro_l1.png) | Previous Track | | ![](../image/retropad/retro_r1.png) | Next Track | ## External Links - [Official Game Music Emu Website](http://blargg.8bitalley.com/libs/audio.html) - [Official Game Music Emu Github Repository](https://bitbucket.org/mpyne/game-music-emu/wiki/Home) - [Libretro Game Music Emu Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/gme_libretro.info) - [Libretro Game Music Emu Github Repository](https://github.com/libretro/libretro-gme) - [Report Libretro Game Music Emu Core Issues Here](https://github.com/libretro/libretro-gme/issues) ================================================ FILE: docs/library/gearboy.md ================================================ # Nintendo - Game Boy / Color (Gearboy) ## Background Gearboy is an open source, cross-platform, Nintendo Game Boy (DMG) / Game Boy Color (GBC) emulator written in C++. - Accurate emulation supporting cartridges: ROM, ROM + RAM, MBC1, MBC2, MBC3, MBC5, MBC7, HuC-1, HuC-3, MMM01, Pocket Camera, TAMA5 and MBC1M. - Game Boy Color support. - Battery powered RAM save support. - Save states. - Bootrom (BIOS) support. - Game Genie and GameShark cheat support. - Supported platforms (libretro): Windows, Linux, macOS, Raspberry Pi, Android, iOS, tvOS, PlayStation Vita, PlayStation 3, Nintendo 3DS, Nintendo GameCube, Nintendo Wii, Nintendo WiiU, Nintendo Switch, Emscripten, Classic Mini systems (NES, SNES, C64, ...), OpenDingux, RetroFW and QNX. The Gearboy core has been authored by: - [Nacho Sanchez (drhelius)](https://github.com/drhelius) The Gearboy core is licensed under: - [GPLv3](https://github.com/drhelius/Gearboy/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Gearboy does not require bootrom (BIOS) files to work but they can be used optionally. When the bootrom is enabled it will execute as in original hardware, causing invalid roms to lock or forcing hardware like GB Pocket or GBA, depending on the bootrom file. Required or optional firmware files go in the frontend's system directory. !!! attention If you’d like to use any bootrom, you can place the following files in RetroArch's system directory. Then, you need to enable [DMG Bootrom](#core-options) and/or [Game Boy Color Bootrom](#core-options) core options for these bootrom files to be used. | Filename | Description | md5sum | |:------------:|:----------------------------------:|:--------------------------------:| | dmg_boot.bin | Game Boy boot ROM - Optional | 32fbbd84168d3482956eb3c5051637f5 | | cgb_boot.bin | Game Boy Color boot ROM - Optional | dbfce9db9deaa2567f6a84fde55f9680 | ## Extensions Content that can be loaded by the Gearboy core have the following file extensions: - .gb - .dmg - .gbc - .cgb - .sgb RetroArch database(s) that are associated with the Gearboy core: - [Nintendo - Game Boy](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Game%20Boy.rdb) - [Nintendo - Game Boy Color](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Game%20Boy%20Color.rdb) ## Features Frontend-level settings or features that the Gearboy core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats - Game Genie | ✔ | | RetroArch Cheats - GameShark | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✔ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Gearboy core's library name is 'Gearboy' The Gearboy core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:----------------------:| | *.srm | Cartridge battery save | | *.rtc | Real time clock save | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ### Geometry and timing - The Gearboy core's core provided FPS is 59.7275005696 - The Gearboy core's core provided sample rate is 44100 Hz - The Gearboy core's base width is 160 - The Gearboy core's base height is 144 - The Gearboy core's max width is 160 - The Gearboy core's max height is 144 - The Gearboy core's core provided aspect ratio is 10/9 ## Core options The Gearboy core has the following options that can be tweaked from the core options menu. The default setting is bolded. Settings with (restart) means that core has to be closed for the new setting to be applied on next launch. - **Game Boy Model (restart)** [gearboy_model] (**Auto**|Game Boy DMG|Game Boy Advance) Select which hardware/model is emulated. - *Auto* selects the best hardware based on the rom. - *Game Boy DMG* forces original Game Boy hardware. - *Game Boy Advance* enables Game Boy Advance hardware. - **Mapper (restart)** [gearboy_mapper] (**Auto**|ROM Only|MBC 1|MBC 2|MBC 3|MBC 5|MBC 1 Multicart|HuC 1|HuC 3|MMM01|Camera|MBC 7|TAMA5) Select which Memory Bank Controller (MBC or mapper) is emulated. - *Auto* selects the best MBC based on the rom. - *ROM Only* forces no MBC. - *MBC 1* forces MBC 1. - *MBC 2* forces MBC 2. - *MBC 3* forces MBC 3. - *MBC 5* forces MBC 5. - *MBC 1 Multicart* forces MBC 1 Multicart. - *HuC 1* forces HuC 1. - *HuC 3* forces HuC 3. - *MMM01* forces MMM01. - *Camera* forces Pocket Camera. - *MBC 7* forces MBC 7. - *TAMA5* forces TAMA5. - **DMG Palette** [gearboy_palette] (**Original**|Sharp|B/W|Autumn|Soft|Slime) Select a color palette for Game Boy DMG games. - **GBC Color Correction** [gearboy_color_correction] (**Disabled**|Enabled) Enables color correction for Game Boy Color games to simulate the original GBC LCD screen output. - **DMG Bootrom (restart)** [gearboy_bootrom_dmg] (**Disabled**|Enabled) Enable or disable the original Game Boy bootrom. For this to work, the `dmg_boot.bin` file must exist in RetroArch's system directory. - **GBC Bootrom (restart)** [gearboy_bootrom_gbc] (**Disabled**|Enabled) Enable or disable the Game Boy Color bootrom. For this to work, the `cgb_boot.bin` file must exist in RetroArch's system directory. - **Allow Up+Down / Left+Right** [gearboy_up_down_allowed] (**Disabled**|Enabled) Allow pressing, quickly alternating, or holding both left and right (or up and down) directions at the same time. This may cause movement based glitches in certain games. - **Tilt Source (MBC7)** [gearboy_tilt_source] (**Mouse**|Sensor|Analog Stick) Select the input source for MBC7 tilt controls. - **Sensor Sensitivity X (MBC7)** [gearboy_sensor_sensitivity_x] (**5**|1-10) Set the horizontal sensitivity when using sensor input for MBC7 tilt controls. - **Sensor Sensitivity Y (MBC7)** [gearboy_sensor_sensitivity_y] (**5**|1-10) Set the vertical sensitivity when using sensor input for MBC7 tilt controls. - **Sensor Invert X (MBC7)** [gearboy_sensor_invert_x] (**Disabled**|Enabled) Invert the horizontal axis when using sensor input for MBC7 tilt controls. - **Sensor Invert Y (MBC7)** [gearboy_sensor_invert_y] (**Disabled**|Enabled) Invert the vertical axis when using sensor input for MBC7 tilt controls. - **Mouse Sensitivity X (MBC7)** [gearboy_mouse_sensitivity_x] (**5**|1-10) Set the horizontal sensitivity when using mouse input for MBC7 tilt controls. - **Mouse Sensitivity Y (MBC7)** [gearboy_mouse_sensitivity_y] (**5**|1-10) Set the vertical sensitivity when using mouse input for MBC7 tilt controls. - **Mouse Invert X (MBC7)** [gearboy_mouse_invert_x] (**Disabled**|Enabled) Invert the horizontal axis when using mouse input for MBC7 tilt controls. - **Mouse Invert Y (MBC7)** [gearboy_mouse_invert_y] (**Disabled**|Enabled) Invert the vertical axis when using mouse input for MBC7 tilt controls. - **Analog Sensitivity X (MBC7)** [gearboy_analog_sensitivity_x] (**5**|1-10) Set the horizontal sensitivity when using analog stick input for MBC7 tilt controls. - **Analog Sensitivity Y (MBC7)** [gearboy_analog_sensitivity_y] (**5**|1-10) Set the vertical sensitivity when using analog stick input for MBC7 tilt controls. - **Analog Invert X (MBC7)** [gearboy_analog_invert_x] (**Disabled**|Enabled) Invert the horizontal axis when using analog stick input for MBC7 tilt controls. - **Analog Invert Y (MBC7)** [gearboy_analog_invert_y] (**Disabled**|Enabled) Invert the vertical axis when using analog stick input for MBC7 tilt controls. ## Joypad ![](../image/controller/gb.png) | User 1 input descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | Up | ![](../image/retropad/retro_dpad_up.png) | | Down | ![](../image/retropad/retro_dpad_down.png) | | Left | ![](../image/retropad/retro_dpad_left.png) | | Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | ## Compatibility - [Gearboy Accuracy Tests](https://github.com/drhelius/Gearboy#accuracy-tests) ## External Links - [Official Gearboy Github Repository](https://github.com/drhelius/Gearboy) - [Libretro Gearboy Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/gearboy_libretro.info) - [Report Libretro Gearboy Core Issues Here](https://github.com/drhelius/Gearboy/issues) ### See also #### Nintendo - Game Boy (+ Color) - [Nintendo - Game Boy / Color (Emux GB)](emux_gb.md) - [Nintendo - Game Boy / Color (Gambatte)](gambatte.md) - [Nintendo - Game Boy / Color (SameBoy)](sameboy.md) - [Nintendo - Game Boy / Color (TGB Dual)](tgb_dual.md) - [Nintendo - Game Boy Advance (mGBA)](mgba.md) - [Nintendo - Game Boy Advance (VBA-M)](vba_m.md) - [Nintendo - SNES / Famicom (higan Accuracy)](higan_accuracy.md) - [Nintendo - SNES / Famicom (nSide Balanced)](nside_balanced.md) - [Nintendo - SNES / Famicom (Mesen-S)](mesen-s.md) ================================================ FILE: docs/library/gearcoleco.md ================================================ # Coleco - ColecoVision (GearColeco) ## Background Gearcoleco is an open source, cross-platform, ColecoVision emulator written in C++. - Accurate Z80 core, including undocumented opcodes and behavior like R and MEMPTR registers. - Accurate TMS9918 emulation. - Support for ColecoVision Super Game Module (SGM) and MegaCart ROMs. - Support for Super Action Controller (SAC), Wheel Controller and Roller Controller. - Supported platforms (libretro): Windows, Linux, macOS, Raspberry Pi, Android, iOS, tvOS, PlayStation Vita, PlayStation 3, Nintendo 3DS, Nintendo GameCube, Nintendo Wii, Nintendo WiiU, Nintendo Switch, Emscripten, Classic Mini systems (NES, SNES, C64, ...), OpenDingux, RetroFW and QNX. The Gearcoleco core has been authored by - [Nacho Sanchez (drhelius)](https://github.com/drhelius) The Gearcoleco core is licensed under - [GPLv3](https://github.com/drhelius/Gearcoleco/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Gearcoleco requires a BIOS file to work. Required or optional firmware files go in the frontend's system directory. !!! attention Gearcoleco emulator requires a ColecoVision BIOS. In order to get it to work you must place the following file in RetroArch's system directory. | Filename | Description | md5sum | |:-----------------:|:----------------------------------:|:--------------------------------:| | colecovision.rom | ColecoVision BIOS - Required | 2c66f5911e5b42b8ebe113403548eee7 | ## Extensions Content that can be loaded by the Gearcoleco core have the following file extensions: - .col - .cv - .bin - .rom RetroArch database(s) that are associated with the Gearcoleco core: - [Coleco - ColecoVision](https://github.com/libretro/libretro-database/blob/master/rdb/Coleco%20-%20ColecoVision.rdb) ## Features Frontend-level settings or features that the Gearcoleco core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✔ | | LEDs | ✕ | ### Directories The Gearcoleco core's library name is 'Gearcoleco' The Gearcoleco core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:----------------------:| | *.srm | Cartridge battery save | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ### Geometry and timing - The Gearcoleco core's core provided FPS is 60 for NTSC games and 50 for PAL games - The Gearcoleco core's core provided sample rate is 44100 Hz - The Gearcoleco core's width is 256 - The Gearcoleco core's height is 192 - The Gearcoleco core's core provided aspect ratio is 4:3 ## Core options The Gearcoleco core has the following options that can be tweaked from the core options menu. The default setting is bolded. Settings with (restart) means that core has to be closed for the new setting to be applied on next launch. - **Refresh Rate (restart)** [gearcoleco_timing] (**Auto**|NTSC (60 Hz)|PAL (50 Hz)) Select which refresh rate will be used in emulation. - *Auto* selects the best refresh rate based on the rom. - *NTSC (60 Hz)* forces 60 Hz. - *PAL (50 Hz)* forces 50 Hz. - **Aspect Ratio** [gearcoleco_aspect_ratio] (**1:1 PAR**|4:3 DAR|16:9 DAR|16:10 DAR) Select which aspect ratio will be presented by the core. - *1:1 PAR* selects an aspect ratio that produces square pixels. - *4:3 DAR* forces 4:3 aspect ratio. - *16:9 DAR* forces 16:9 aspect ratio. - *16:10 DAR* forces 16:10 aspect ratio. - **Overscan** [gearcoleco_overscan] (**Disabled**|Top+Bottom|Full (284 width)|Full (320 width)) Select which overscan (borders) will be used in emulation. - *Disabled* disables overscan. - *Top+Bottom* enables overscan for top and bottom. - *Full (284 width)* enables overscan for top, bottom, left and right (284 width). - *Full (320 width)* enables overscan for top, bottom, left and right (320 width). - **Allow Up+Down / Left+Right** [gearcoleco_up_down_allowed] (**Disabled**|Enabled) Enabling this option allows pressing, quickly alternating, or holding both left and right (or up and down in some games) directions at the same time. This may cause movement based glitches to occur in certain games. It's best to keep this core option disabled. - **No Sprite Limit** [gearcoleco_no_sprite_limit] (**Disabled**|Enabled) Enabling this will remove the sprite limit in a single line. This may cause glitches to occur in certain games. It's best to keep this core option disabled. - **Spinner Support** [gearcoleco_spinners] (**Disabled**|Super Action Controller|Wheel Controller|Roller Controller) Select which controller will be used in emulation. Spinners are controlled by mouse movement. Mouse buttons are mapped to Left (Yellow) and Right (Red) buttons. - *Disabled* disables spinner support. - *Super Action Controller* enables spinner support for Super Action Controller. - *Wheel Controller* enables spinner support for Wheel Controller. - *Roller Controller* enables spinner support for Roller Controller. - **Spinner Sensitivity** [gearcoleco_spinner_sensitivity] (**1**|1-10) Select the spinner sensitivity. - *1* is the lowest sensitivity. - *10* is the highest sensitivity. ### Joypad | Coleco Controller | RetroPad Inputs | |-------------------------------------|------------------------------------------------| | Joystick Up | ![](../image/retropad/retro_dpad_up.png) | | Joystick Down | ![](../image/retropad/retro_dpad_down.png) | | Joystick Left | ![](../image/retropad/retro_dpad_left.png) | | Joystick Right | ![](../image/retropad/retro_dpad_right.png) | | Yellow (Left) | ![](../image/retropad/retro_b.png) | | Red (Right) | ![](../image/retropad/retro_a.png) | | Keypad 1 | ![](../image/retropad/retro_y.png) | | Keypad 2 | ![](../image/retropad/retro_x.png) | | Keypad 3 | ![](../image/retropad/retro_l1.png) | | Keypad 4 | ![](../image/retropad/retro_r1.png) | | Keypad 5 | ![](../image/retropad/retro_l2.png) | | Keypad 6 | ![](../image/retropad/retro_r2.png) | | Keypad 7 | ![](../image/retropad/retro_l3.png) | | Keypad 8 | ![](../image/retropad/retro_r3.png) | | Keypad * | ![](../image/retropad/retro_start.png) | | Keypad # | ![](../image/retropad/retro_select.png) | | Keypad 9 | ![](../image/retropad/retro_left_stick.png) Left Analog Y | | Keypad 0 | ![](../image/retropad/retro_left_stick.png) Left Analog X | | Purple | ![](../image/retropad/retro_right_stick.png) Right Analog Y | | Blue | ![](../image/retropad/retro_right_stick.png) Right Analog X | ## External Links - [Official Gearcoleco Repository](https://github.com/drhelius/Gearcoleco) - [Libretro Gearcoleco Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/gearcoleco_libretro.info) - [Report Gearcoleco Core Issues Here](https://github.com/drhelius/Gearcoleco/issues) ### See also - [ColecoVision/CreatiVision/My Vision (JollyCV)](jollycv.md) - [MSX/SVI/ColecoVision/SG-1000 (blueMSX)](bluemsx.md) ================================================ FILE: docs/library/geargrafx.md ================================================ # NEC - PC Engine / SuperGrafx (Geargrafx) ## Background Geargrafx is an open source, cross-platform, PC Engine / TurboGrafx-16 / SuperGrafx emulator written in C++. - Very accurate emulation supporting the entire HuCard PCE / SGX catalog. - Support for CD-ROM², Super CD-ROM² and Arcade CD-ROM² systems. - Backup RAM and Memory Base 128 support. - Multi Tap support (up to 5 players). - Controllers: * Standard Gamepad (2 buttons) * Avenue Pad 3 (3 buttons, auto-configured based on game) * Avenue Pad 6 (6 buttons) - Adjustable scanline count (224p, 240p, or manual). - RGB or Composite color output. - Music rom support: HES. - Internal database for automatic rom detection and hardware selection if `Auto` options are selected. - Supported platforms (libretro): Windows, Linux, macOS, Raspberry Pi, Android, iOS, tvOS, PlayStation Vita, PlayStation 3, Nintendo 3DS, Nintendo GameCube, Nintendo Wii, Nintendo WiiU, Nintendo Switch, Emscripten, Classic Mini systems (NES, SNES, C64, etc.), OpenDingux, RetroFW and QNX. The Geargrafx core has been authored by - [Nacho Sanchez (drhelius)](https://github.com/drhelius) The Geargrafx core is licensed under - [GPLv3](https://github.com/drhelius/Geargrafx/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Geargrafx requires a BIOS file to run CD-ROM games. Required or optional firmware files go in RetroArch's system directory. !!! attention Any CD-ROM System BIOS will work, but some are known to be incompatible with certain games. !!! attention You can choose the BIOS to use in the core options menu. | Filename | Description | md5sum | |:-------------:|:-------------------------------------:|:--------------------------------:| | syscard3.pce | Super CD-ROM2 System V3.xx - Required | 38179df8f4ac870017db21ebcbf53114 | | syscard2.pce | CD-ROM System V2.xx - Optional | | | syscard1.pce | CD-ROM System V1.xx - Optional | | | gexpress.pce | Game Express CD Card - Optional | | ## Extensions Content that can be loaded by the Geargrafx core have the following file extensions: - .pce - .sgx - .hes - .cue - .chd Geargrafx supports `chd`, `cue/bin`, `cue/img` and `cue/iso` CD-ROM images. `cue/iso + wav` is also supported when audio track format is 44100Hz, 16 bit, stereo. It does not support MP3 or OGG audio tracks. RetroArch database(s) that are associated with the Geargrafx core: - [NEC - PC Engine - TurboGrafx 16](https://github.com/libretro/libretro-database/blob/master/rdb/NEC%20-%20PC%20Engine%20-%20TurboGrafx%2016.rdb) - [NEC - PC Engine SuperGrafx](https://github.com/libretro/libretro-database/blob/master/rdb/NEC%20-%20PC%20Engine%20SuperGrafx.rdb) - [NEC - PC Engine CD - TurboGrafx-CD](https://github.com/libretro/libretro-database/blob/master/rdb/NEC%20-%20PC%20Engine%20CD%20-%20TurboGrafx-CD.rdb) ## Features Frontend-level settings or features that the Geargrafx core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✔ | | LEDs | ✕ | ## Directories The Geargrafx core's library name is 'Geargrafx' The Geargrafx core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:----------------------:| | *.srm | Cartridge battery save | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ## Geometry and timing - The Geargrafx core's provided FPS is 59.82 - The Geargrafx core's provided sample rate is 44100 Hz - The Geargrafx core's base width is dependent on the content and overscan settings (Without overscan: 256, 341, 512. With overscan: 280, 373, 560) - The Geargrafx core's base height is dependent on the ['Scanline Start' and 'Scanline End' core options](#core-options). - The Geargrafx core's max width is 560 - The Geargrafx core's max height is 242 - The Geargrafx core's provided aspect ratio is dependent on the ['Aspect Ratio' core option](#core-options). ## Core options The Geargrafx core has the following options that can be tweaked from the core options menu. The default setting is bolded. Settings with (restart) means that core has to be closed for the new setting to be applied on next launch. - **System (restart)** [geargrafx_console_type] (**Auto**|PC Engine (JAP)|SuperGrafx (JAP)|TurboGrafx-16 (USA)) Select the console type to emulate. The default setting, Auto, automatically detects the appropriate console type based on the loaded content. Many US games will not start if a Japanese system is detected. - **Aspect Ratio** [geargrafx_aspect_ratio] (**1:1 PAR**|4:3 DAR|6:5 DAR|16:9 DAR|16:10 DAR) Select which aspect ratio will be presented by the core. - *1:1 PAR* selects an aspect ratio that produces square pixels. - *4:3 DAR* forces 4:3 aspect ratio. - *6:5 DAR* forces 6:5 aspect ratio. - *16:9 DAR* forces 16:9 aspect ratio. - *16:10 DAR* forces 16:10 aspect ratio. - **Overscan** [geargrafx_overscan] (**Disabled**|Enabled) This option enables/disables overscan (borders). Overscan width is dependent on the content. - **Scanline Count** [geargrafx_scanline_count] (**224p**|240p|Manual) Select which scanline count will be used in emulation. - *224p* forces 224 scanlines. - *240p* forces 240 scanlines. - *Manual* lets you set the first and last scanline manually. - **Scanline Start (Manual)** [geargrafx_scanline_start] (**3**|values from 0 to 30) This option will set the first scanline to be displayed. Scanline 0 is the first visible scanline. This option is only available when 'Scanline Count' is set to 'Manual'. - **Scanline End (Manual)** [geargrafx_scanline_end] (**241**|values from 220 to 241) This option will set the last scanline to be displayed. Scanline 241 is the last visible scanline. This option is only available when 'Scanline Count' is set to 'Manual'. - **Composite Colors** [geargrafx_composite_colors] (**Disabled**|Enabled) If enabled, the core will use composite colors instead of RGB colors. - **No Sprite Limit** [geargrafx_no_sprite_limit] (**Disabled**|Enabled) Remove the per-line sprite limit. This reduces flickering but may cause glitches in certain games. It's best to keep this option disabled. - **Video Low-Pass Filter** [geargrafx_lowpass_filter] (**Disabled**|Enabled) Enable a low-pass video filter to simulate the signal degradation of analog video output on CRT displays. - **Video LPF Intensity** [geargrafx_lowpass_intensity] (**100**|0 - 100) Set the intensity of the video low-pass filter as a percentage from 0 to 100. - **Video LPF Cutoff** [geargrafx_lowpass_cutoff] (**5.0 MHz**|3.0 MHz|3.5 MHz|4.0 MHz|4.5 MHz|5.0 MHz|5.5 MHz|6.0 MHz|6.5 MHz|7.0 MHz) Set the cutoff frequency of the video low-pass filter. Lower values produce a softer image. - **Video LPF HuC6270 5.36 MHz** [geargrafx_lowpass_speed_536] (**Disabled**|Enabled) Apply the video low-pass filter when HuC6270 is running in 5.36 MHz dot clock mode (256px width). - **Video LPF HuC6270 7.16 MHz** [geargrafx_lowpass_speed_716] (**Enabled**|Disabled) Apply the video low-pass filter when HuC6270 is running in 7.16 MHz dot clock mode (341px width). - **Video LPF HuC6270 10.8 MHz** [geargrafx_lowpass_speed_108] (**Enabled**|Disabled) Apply the video low-pass filter when HuC6270 is running in 10.8 MHz dot clock mode (512px width). - **Backup RAM (restart)** [geargrafx_backup_ram] (**Enabled**|Disabled) This option allows you to disable backup RAM (not recommended). - **Deterministic Netplay** [geargrafx_deterministic_netplay] (**Disabled**|Enabled) When enabled, ensures deterministic emulation behavior for netplay by setting consistent reset values for memory and hardware registers. This helps prevent desyncs during netplay sessions. - **Safe VDC Defaults (Homebrew)** [geargrafx_safe_vdc_defaults] (**Disabled**|Enabled) When enabled, sets safe default values for the VDC (Video Display Controller) registers. This can help some homebrew software run correctly. - **CD-ROM (restart)** [geargrafx_cdrom_type] (**Auto**|Standard|Super CD-ROM|Arcade CD-ROM) Select the CD-ROM system type. The *Auto* setting automatically selects the appropriate CD-ROM system based on the loaded content. - *Auto* selects the best CD-ROM system based on the content. - *Standard* forces standard CD-ROM² system. - *Super CD-ROM* forces Super CD-ROM² system. - *Arcade CD-ROM* forces Arcade CD-ROM² system. - **CD-ROM Bios (restart)** [geargrafx_cdrom_bios] (**Auto**|System Card 1|System Card 2|System Card 3|Game Express) Specify the BIOS file to use for CD-ROM emulation. The *Auto* setting automatically selects the appropriate BIOS based on the loaded content. You can also manually choose one for compatibility with specific games. - **Preload CD-ROM (restart)** [geargrafx_cdrom_preload] (**Disabled**|Enabled) This option will preload all CD-ROM tracks in RAM. It will increase the memory usage of the core, but may improve performance. - **HuC6280A Audio Chip** [geargrafx_psg_huc6280a] (**Enabled**|Disabled) Enable the HuC6280A audio chip, as found in the SuperGrafx and CoreGrafx I. When disabled, the original HuC6280 chip from the PC Engine is used instead. - **PSG Volume** [geargrafx_psg_volume] (**100**|0 - 200) This option sets the volume of the PSG (Programmable Sound Generator) sound system. The value is a percentage from 0 to 200, where 100 is the default volume. - **CD-ROM Volume** [geargrafx_cdrom_volume] (**100**|0 - 200) This option sets the volume of the CD-ROM sound system, which is used for music in CD-ROM games. The value is a percentage from 0 to 200, where 100 is the default volume. - **ADPCM Volume** [geargrafx_adpcm_volume] (**100**|0 - 200) This option sets the volume of the ADPCM sound system, which is typically used for speech in CD-ROM games. The value is a percentage from 0 to 200, where 100 is the default volume. - **Allow Up+Down / Left+Right** [geargrafx_up_down_allowed] (**Disabled**|Enabled) Enabling this option allows pressing, quickly alternating, or holding both left and right (or up and down in some games) directions at the same time. This may cause movement based glitches to occur in certain games. It's best to keep this core option disabled. - **Allow Soft Reset** [geargrafx_soft_reset] (**Enabled**|Disabled) Pressing RUN and SELECT simultaneously on the PCE gamepad will SOFT RESET the console. This is the default hardware behavior. Disable this option if you want the soft reset functionality turned off. - **TurboTap** [geargrafx_turbotap] (**Disabled**|Enabled) This option enables/disables TurboTap support (up to 5 players). - **MB128 Backup Memory** [geargrafx_mb128] (**Auto**|Enabled|Disabled) Enable or disable MB128 backup memory support. MB128 is an external memory card device that can be used to save game data across multiple games. - **Avenue Pad 3 Switch** [geargrafx_avenue_pad_3_switch] (**Auto**|SELECT|RUN) Configure the button mapping for the Avenue Pad 3 controller's third button (III). - *Auto* automatically selects the appropriate button mapping based on the game. - *SELECT* maps button III to SELECT. - *RUN* maps button III to RUN. - **P1 Turbo I** [geargrafx_turbo_p1_i] (**Disabled**|Enabled) Enables/disables the Turbo I button for Player 1. - **P1 Turbo II** [geargrafx_turbo_p1_ii] (**Disabled**|Enabled) Enables/disables the Turbo II button for Player 1. - **P2 Turbo I** [geargrafx_turbo_p2_i] (**Disabled**|Enabled) Enables/disables the Turbo I button for Player 2. - **P2 Turbo II** [geargrafx_turbo_p2_ii] (**Disabled**|Enabled) Enables/disables the Turbo II button for Player 2. - **P3 Turbo I** [geargrafx_turbo_p3_i] (**Disabled**|Enabled) Enables/disables the Turbo I button for Player 3. - **P3 Turbo II** [geargrafx_turbo_p3_ii] (**Disabled**|Enabled) Enables/disables the Turbo II button for Player 3. - **P4 Turbo I** [geargrafx_turbo_p4_i] (**Disabled**|Enabled) Enables/disables the Turbo I button for Player 4. - **P4 Turbo II** [geargrafx_turbo_p4_ii] (**Disabled**|Enabled) Enables/disables the Turbo II button for Player 4. - **P5 Turbo I** [geargrafx_turbo_p5_i] (**Disabled**|Enabled) Enables/disables the Turbo I button for Player 5. - **P5 Turbo II** [geargrafx_turbo_p5_ii] (**Disabled**|Enabled) Enables/disables the Turbo II button for Player 5. - **P1 Turbo I Speed** [geargrafx_turbo_speed_p1_i] (**4**|values from 1 to 15) Number of frames between each button I toggle for Player 1. - **P1 Turbo II Speed** [geargrafx_turbo_speed_p1_ii] (**4**|values from 1 to 15) Number of frames between each button II toggle for Player 1. - **P2 Turbo I Speed** [geargrafx_turbo_speed_p2_i] (**4**|values from 1 to 15) Number of frames between each button I toggle for Player 2. - **P2 Turbo II Speed** [geargrafx_turbo_speed_p2_ii] (**4**|values from 1 to 15) Number of frames between each button II toggle for Player 2. - **P3 Turbo I Speed** [geargrafx_turbo_speed_p3_i] (**4**|values from 1 to 15) Number of frames between each button I toggle for Player 3. - **P3 Turbo II Speed** [geargrafx_turbo_speed_p3_ii] (**4**|values from 1 to 15) Number of frames between each button II toggle for Player 3. - **P4 Turbo I Speed** [geargrafx_turbo_speed_p4_i] (**4**|values from 1 to 15) Number of frames between each button I toggle for Player 4. - **P4 Turbo II Speed** [geargrafx_turbo_speed_p4_ii] (**4**|values from 1 to 15) Number of frames between each button II toggle for Player 4. - **P5 Turbo I Speed** [geargrafx_turbo_speed_p5_i] (**4**|values from 1 to 15) Number of frames between each button I toggle for Player 5. - **P5 Turbo II Speed** [geargrafx_turbo_speed_p5_ii] (**4**|values from 1 to 15) Number of frames between each button II toggle for Player 5. ## Joypad | RetroPad Inputs | PCE Pad (2-button) | Avenue Pad 3 (3-button) | Avenue Pad 6 (6-button) | |---------------------------------------------|--------------------|----------------------------|-------------------------| | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | D-Pad Up | D-Pad Up | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | D-Pad Down | D-Pad Down | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | D-Pad Left | D-Pad Left | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | D-Pad Right | D-Pad Right | | ![](../image/retropad/retro_select.png) | Select | Select | Select | | ![](../image/retropad/retro_start.png) | Run | Run | Run | | ![](../image/retropad/retro_a.png) | I | I | I | | ![](../image/retropad/retro_b.png) | II | II | II | | ![](../image/retropad/retro_y.png) | | III (mapped to Select/Run) | III | | ![](../image/retropad/retro_x.png) | | | IV | | ![](../image/retropad/retro_l1.png) | | | V | | ![](../image/retropad/retro_r1.png) | | | VI | | ![](../image/retropad/retro_l2.png) | Toggle Turbo II | Toggle Turbo II | Toggle Turbo II | | ![](../image/retropad/retro_r2.png) | Toggle Turbo I | Toggle Turbo I | Toggle Turbo I | ## External Links - [Official Geargrafx Repository](https://github.com/drhelius/Geargrafx) - [Libretro Geargrafx Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/geargrafx_libretro.info) - [Report Libretro Geargrafx Core Issues Here](https://github.com/drhelius/Geargrafx/issues) ================================================ FILE: docs/library/gearlynx.md ================================================ # Atari - Lynx (Gearlynx) ## Background Gearlynx is an open source, cross-platform, Atari Lynx emulator written in C++. - Very accurate emulation supporting the entire commercial Atari Lynx catalog. - Bank switching (BANK1 + AUDIN) and EEPROM support. - Save files (EEPROM and NVRAM). - Configurable low-pass audio filter. - Internal database for automatic rom detection and hardware selection if `Auto` options are selected. - Supported platforms (libretro): Windows, Linux, macOS, Raspberry Pi, Android, iOS, tvOS, PlayStation Vita, PlayStation 3, Nintendo 3DS, Nintendo GameCube, Nintendo Wii, Nintendo WiiU, Nintendo Switch, Emscripten, Classic Mini systems (NES, SNES, C64, ...), OpenDingux, RetroFW and QNX. The Gearlynx core has been authored by: - [Nacho Sanchez (drhelius)](https://github.com/drhelius) The Gearlynx core is licensed under: - [GPLv3](https://github.com/drhelius/Gearlynx/blob/main/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Gearlynx requires a BIOS to work. Required firmware files go in the frontend's system directory. !!! attention The Lynx boot ROM file is required for Gearlynx to function. | Filename | Description | md5sum | |:------------:|:----------------------------:|:--------------------------------:| | lynxboot.img | Lynx Boot Image - Required | fcd403db69f54290b51035d82f835e7b | ## Extensions Content that can be loaded by the Gearlynx core have the following file extensions: - .lnx - .lyx - .o RetroArch database(s) that are associated with the Gearlynx core: - [Atari - Lynx](https://github.com/libretro/libretro-database/blob/master/rdb/Atari%20-%20Lynx.rdb) ## Features Frontend-level settings or features that the Gearlynx core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Gearlynx core's library name is 'Gearlynx' The Gearlynx core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:----------------------:| | *.srm | EEPROM / NVRAM save | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ### Geometry and timing - The Gearlynx core's core provided FPS is variable from 50 to 75 - The Gearlynx core's core provided sample rate is 44100 Hz - The Gearlynx core's base width is 160 - The Gearlynx core's base height is 102 - The Gearlynx core's max width is 160 - The Gearlynx core's max height is 102 - The Gearlynx core's provided aspect ratio is dependent on the ['Aspect Ratio' core option](#core-options). ## Core options The Gearlynx core has the following options that can be tweaked from the core options menu. The default setting is bolded. Settings with (restart) means that core has to be closed for the new setting to be applied on next launch. - **Aspect Ratio** [gearlynx_aspect_ratio] (**1:1 PAR**|4:3 DAR|16:9 DAR|16:10 DAR) Select which aspect ratio will be presented by the core. - *1:1 PAR* selects an aspect ratio that produces square pixels. - *4:3 DAR* forces 4:3 aspect ratio. - *16:9 DAR* forces 16:9 aspect ratio. - *16:10 DAR* forces 16:10 aspect ratio. - **Screen Rotation** [gearlynx_rotation] (**Auto**|Left|Right|Disabled) Rotates the screen display. This is useful since many Lynx games were designed to be played with the system held vertically. - *Auto* automatically rotates based on the game. - *Left* rotates the screen 90 degrees counter-clockwise. - *Right* rotates the screen 90 degrees clockwise. - *Disabled* forces the screen to remain in standard horizontal orientation. - **Console Type** [gearlynx_console_type] (**Auto**|Lynx I|Lynx II) Select the Atari Lynx console model to emulate. - *Auto* automatically selects the appropriate console type based on the game. - *Lynx I* forces emulation of the original Lynx model. - *Lynx II* forces emulation of the Lynx II model. - **Audio Low-Pass Filter (Hz)** [gearlynx_lowpass_filter] (**3500**|500|1000|1500|2000|2500|3000|3500|4000|4500|5000) Configures a low-pass audio filter to reduce high-frequency noise. - **Audio Channel 0 Volume** [gearlynx_audio_ch0_volume] (**100**|0-200) Sets the volume level for audio channel 0 (percentage). - **Audio Channel 1 Volume** [gearlynx_audio_ch1_volume] (**100**|0-200) Sets the volume level for audio channel 1 (percentage). - **Audio Channel 2 Volume** [gearlynx_audio_ch2_volume] (**100**|0-200) Sets the volume level for audio channel 2 (percentage). - **Audio Channel 3 Volume** [gearlynx_audio_ch3_volume] (**100**|0-200) Sets the volume level for audio channel 3 (percentage). - **Allow Up+Down / Left+Right** [gearlynx_up_down_allowed] (**Disabled**|Enabled) Enabling this option allows pressing, quickly alternating, or holding both left and right (or up and down) directions at the same time. This may cause movement based glitches to occur in certain games. It's best to keep this core option disabled. ## Joypad ![](../image/controller/lynx.png) | User 1 input descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Pause | ![](../image/retropad/retro_start.png) | | Up | ![](../image/retropad/retro_dpad_up.png) | | Down | ![](../image/retropad/retro_dpad_down.png) | | Left | ![](../image/retropad/retro_dpad_left.png) | | Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | Option 1 | ![](../image/retropad/retro_l1.png) | | Option 2 | ![](../image/retropad/retro_r1.png) | ## Compatibility - [Gearlynx Hardware Tests](https://github.com/drhelius/lynx-tests) ## External Links - [Official Gearlynx Github Repository](https://github.com/drhelius/Gearlynx) - [Libretro Gearlynx Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/gearlynx_libretro.info) - [Report Libretro Gearlynx Core Issues Here](https://github.com/drhelius/Gearlynx/issues) ### See also #### Atari - Lynx - [Atari - Lynx (Beetle Lynx)](beetle_lynx.md) - [Atari - Lynx (Handy)](handy.md) - [Atari - Lynx (Holani)](holani.md) ================================================ FILE: docs/library/gearsystem.md ================================================ # Sega - MS/GG (Gearsystem) ## Background Gearsystem is an open source, cross-platform, Sega Master System / Game Gear / SG-1000 / Othello Multivision emulator written in C++. - Very accurate emulation supporting cartridges: ROM, ROM + RAM, SEGA, Codemasters, Korean, MSX + Nemesis, Janggun, SG-1000, and many Korean multi-carts. - Automatic region detection: NTSC-JAP, NTSC-USA, PAL-EUR. - Accurate VDP emulation, including timing and VDP specifics for SMS, SMS2, GG and TMS9918 modes. - Support for YM2413 (OPLL) FM sound chip. - Light Phaser and Paddle Control support. - Internal database for ROM detection. - Battery powered RAM save support. - Game Genie and Pro Action Replay cheat support. - Supported platforms (libretro): Windows, Linux, macOS, Raspberry Pi, Android, iOS, tvOS, PlayStation Vita, PlayStation 3, Nintendo 3DS, Nintendo GameCube, Nintendo Wii, Nintendo WiiU, Nintendo Switch, Emscripten, Classic Mini systems (NES, SNES, C64, ...), OpenDingux, RetroFW and QNX. The Gearsystem core has been authored by - [Nacho Sanchez (drhelius)](https://github.com/drhelius) The Gearsystem core is licensed under - [GPLv3](https://github.com/drhelius/Gearsystem/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Gearsystem does not require BIOS (bootrom) files to work but they can be used optionally. When the BIOS is enabled it will execute as in original hardware, causing invalid roms to lock or preventing them to boot, depending on the BIOS file and rom region and system. If you experience issues disable the BIOS. Required or optional firmware files go in the frontend's system directory. !!! attention If you’d like to use any BIOS, you can place the following files in RetroArch's system directory. Then, you need to enable [Master System BIOS](#core-options) and/or [Game Gear BIOS](#core-options) core options for these BIOS files to be used. | Filename | Description | md5sum | |:------------:|:----------------------------------:|:--------------------------------:| | bios.sms | Master System BIOS - Optional | 840481177270d5642a14ca71ee72844c | | bios.gg | Game Gear BIOS - Optional | 672e104c3be3a238301aceffc3b23fd6 | ## Extensions Content that can be loaded by the Gearsystem core have the following file extensions: - .sms - .gg - .sg - .mv - .bin - .rom RetroArch database(s) that are associated with the Gearsystem core: - [Sega - Game Gear](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20Game%20Gear.rdb) - [Sega - Master System - Mark III](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20Master%20System%20-%20Mark%20III.rdb) - [Sega - SG-1000](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20SG-1000.rdb) ## Features Frontend-level settings or features that the Gearsystem core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats - Game Genie | ✔ | | RetroArch Cheats - Pro Action Replay | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✔ | | LEDs | ✕ | ### Directories The Gearsystem core's library name is 'Gearsystem' The Gearsystem core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:----------------------:| | *.srm | Cartridge battery save | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ### Geometry and timing - The Gearsystem core's core provided FPS is 60 for NTSC games and 50 for PAL games - The Gearsystem core's core provided sample rate is 44100 Hz - The Gearsystem core's base width is 256 for Master System / SG-1000 games and 160 for Game Gear games - The Gearsystem core's base height is 192 for Master System / SG-1000 games and 144 for Game Gear games - The Gearsystem core's max width is 256 for Master System games and 160 for Game Gear games - The Gearsystem core's max height is 224 for Master System games and 144 for Game Gear games - The Gearsystem core's core provided aspect ratio is 4:3 for Master System / SG-1000 games and 10:9 for Game Gear games ## Core options The Gearsystem core has the following options that can be tweaked from the core options menu. The default setting is bolded. Settings with (restart) means that core has to be closed for the new setting to be applied on next launch. - **System (restart)** [gearsystem_system] (**Auto**|Master System / Mark III|Game Gear (2 ASIC)|Game Gear (2 ASIC) SMS Mode|Game Gear (1 ASIC)|Game Gear (1 ASIC) SMS Mode|SG-1000 / Multivision|SG-1000 II) Select the console type to emulate. 'Auto' automatically detects the appropriate system based on the loaded content. - *Auto* selects the best hardware based on the rom. - *Master System / Mark III* forces original Master System / Mark III hardware. - *Game Gear (2 ASIC)* forces Game Gear hardware with 2 ASIC configuration. - *Game Gear (2 ASIC) SMS Mode* forces Game Gear in SMS compatibility mode (2 ASIC). - *Game Gear (1 ASIC)* forces Game Gear hardware with 1 ASIC configuration. - *Game Gear (1 ASIC) SMS Mode* forces Game Gear in SMS compatibility mode (1 ASIC). - *SG-1000 / Multivision* forces SG-1000 / Multivision hardware. - *SG-1000 II* forces SG-1000 II hardware. - **Region (restart)** [gearsystem_region] (**Auto**|Master System Japan|Master System Export|Game Gear Japan|Game Gear Export|Game Gear International) Select which region is emulated. - *Auto* selects the best region based on the rom. - *Master System Japan* forces Master System Japan region. - *Master System Export* forces Master System Export region. - *Game Gear Japan* forces Game Gear Japan region. - *Game Gear Export* forces Game Gear Export region. - *Game Gear International* forces Game Gear International region. - **Mapper (restart)** [gearsystem_mapper] (**Auto**|ROM|SEGA|Codemasters|Korean|SG-1000|MSX|Janggun|Korean 2000 XOR 1F|Korean MSX 32KB 2000|Korean MSX SMS 8000|Korean SMS 32KB 2000|Korean MSX 8KB 0300|Korean 0000 XOR FF|Korean FFFF HiCom|Korean FFFE|Korean BFFC|Korean FFF3 FFFC|Korean MD FFF5|Korean MD FFF0|Jumbo Dahjee|EEPROM 93C46|Multi 4PAK All Action|Iratahack) Select which mapper (memory bank controller) is emulated. 'Auto' automatically detects the appropriate mapper based on the loaded content. Only change this if a game does not work correctly with the default setting. - *Auto* selects the best mapper based on the rom. - *ROM* forces no mapper. - *SEGA* forces SEGA mapper. - *Codemasters* forces Codemasters mapper. - *Korean* forces Korean mapper. - *SG-1000* forces SG-1000 mapper. - *MSX* forces MSX mapper. - *Janggun* forces Janggun mapper. - **Refresh Rate (restart)** [gearsystem_timing] (**Auto**|NTSC (60 Hz)|PAL (50 Hz)) Select which refresh rate will be used in emulation. - *Auto* selects the best refresh rate based on the rom. - *NTSC (60 Hz)* forces 60 Hz. - *PAL (50 Hz)* forces 50 Hz. - **Aspect Ratio** [gearsystem_aspect_ratio] (**1:1 PAR**|4:3 DAR|16:9 DAR|16:10 DAR) Select which aspect ratio will be presented by the core. - *1:1 PAR* selects an aspect ratio that produces square pixels. - *4:3 DAR* forces 4:3 aspect ratio. - *16:9 DAR* forces 16:9 aspect ratio. - *16:10 DAR* forces 16:10 aspect ratio. - **Overscan** [gearsystem_overscan] (**Disabled**|Top+Bottom|Full (284 width)|Full (320 width)) Select which overscan (borders) will be used in emulation. - *Disabled* disables overscan. - *Top+Bottom* enables overscan for top and bottom. - *Full (284 width)* enables overscan for top, bottom, left and right (284 width). - *Full (320 width)* enables overscan for top, bottom, left and right (320 width). - **Hide Left Bar (SMS only)** [gearsystem_hide_left_bar] (**No**|Auto|Always) Select when to hide the left bar in Master System games. - *No* never hides the left bar. - *Auto* hides the left bar when the bar is detected. - *Always* always hides the left bar even if no left bar is detected. - **Master System BIOS (restart)** [gearsystem_bios_sms] (**Disabled**|Enabled) Enable or disable the Master System BIOS. For this to work, the `bios.sms` file must exist in RetroArch's system directory. When enabled it will execute as in original hardware, which may cause invalid ROMs to lock or fail to boot. - **Game Gear BIOS (restart)** [gearsystem_bios_gg] (**Disabled**|Enabled) Enable or disable the Game Gear BIOS. For this to work, the `bios.gg` file must exist in RetroArch's system directory. When enabled it will execute as in original hardware, which may cause invalid ROMs to lock or fail to boot. - **YM2413 (restart)** [gearsystem_ym2413] (**Auto**|Disabled) Enable or disable the YM2413 (OPLL) FM sound chip. 'Auto' enables the chip based on the loaded content. Some Master System games use this chip for enhanced music. - *Auto* selects the best option based on the rom. - *Disabled* disables YM2413. - **PSG Volume** [gearsystem_psg_volume] (**100**|0 - 200) Set the volume of the PSG (SN76489). The value is a percentage from 0 to 200, where 100 is the default volume. - **FM Volume** [gearsystem_fm_volume] (**100**|0 - 200) Set the volume of the YM2413 (OPLL) FM sound chip. The value is a percentage from 0 to 200, where 100 is the default volume. - **3D Glasses** [gearsystem_glasses] (**Both Eyes / OFF**|Left Eye|Right Eye) For games with 3D glasses support this option will let you choose to display only left or right eye. - *Both Eyes / OFF* is required for games with NO 3D support or if you want to display both eyes in 3D games. - *Left Eye* displays the left eye only. - *Right Eye* displays the right eye only. - **Allow Up+Down / Left+Right** [gearsystem_up_down_allowed] (**Disabled**|Enabled) Enabling this option allows pressing, quickly alternating, or holding both left and right (or up and down in some games) directions at the same time. This may cause movement based glitches to occur in certain games. It's best to keep this core option disabled. - **Light Gun Input** [gearsystem_lightgun_input] (**Light Gun**|Touchscreen) Select which input will be used for Light Phaser games. - *Light Gun* - Selects mouse-controlled 'Light Gun' input (devices will use [RetroLightgun](#lightgun) inputs). - *Touchscreen* - Selects a touchscreen input (devices will use [RetroPointer](#pointer) inputs instead). - **Light Gun Crosshair** [gearsystem_lightgun_crosshair] (**Disabled**|Enabled) Enable or disable the crosshair for Light Phaser games. - **Light Gun Crosshair Shape** [gearsystem_lightgun_shape] (**Cross**|Square) Select the shape of the crosshair for Light Phaser games. - **Light Gun Crosshair Color** [gearsystem_lightgun_color] (**White**|Black|Red|Green|Blue|Yellow|Magenta|Cyan) Select the color of the crosshair for Light Phaser games. - **Light Gun Crosshair Offset X** [gearsystem_lightgun_crosshair_offset_x] (**0**|-10 - 10) Set the horizontal pixel offset of the crosshair for calibration. - **Light Gun Crosshair Offset Y** [gearsystem_lightgun_crosshair_offset_y] (**0**|-10 - 10) Set the vertical pixel offset of the crosshair for calibration. - **Paddle Sensitivity** [gearsystem_paddle_sensitivity] (**1**|1-15) Set the sensitivity of the [Paddle Control](#mouse). - *1* is the lowest sensitivity. - *15* is the highest sensitivity. ## Joypad ![](../image/controller/gg.png) ![](../image/controller/sms.png) ![](../image/controller/sg1000.png) | RetroPad Inputs | SMS / GG Pad | |------------------------------------------------|--------------------------| | ![](../image/retropad/retro_dpad_up.png) | Up | | ![](../image/retropad/retro_dpad_down.png) | Down | | ![](../image/retropad/retro_dpad_left.png) | Left | | ![](../image/retropad/retro_dpad_right.png) | Right | | ![](../image/retropad/retro_b.png) | 1 | | ![](../image/retropad/retro_a.png) | 2 | | ![](../image/retropad/retro_start.png) | Pause / Start | ## Lightgun | RetroLightgun Inputs | [Light Phaser](https://segaretro.org/Light_Phaser) | |-----------------------|---------------------------------------------------------| | ![](../image/retromouse/retro_mouse.png) Gun Crosshair | Light Phaser Crosshair | | Gun Trigger | Light Phaser Trigger | ## Pointer | RetroPointer Inputs | [Light Phaser](https://segaretro.org/Light_Phaser) | |-----------------------|-----------------------------------------------------------| | ![](../image/retromouse/retro_mouse.png) or ![](../image/Button_Pack/Gestures/Gesture_Finger_Front.png) Pointer Position | Light Phaser Crosshair | | ![](../image/retromouse/retro_left.png) Mouse 1 | Light Phaser Trigger | ## Mouse | RetroMouse Inputs | [Paddle Control](https://segaretro.org/Paddle_Control) | |-------------------------------------------------------|-----------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Paddle wheel | | ![](../image/retromouse/retro_left.png) Mouse 1 | Paddle button | ## Compatibility - [Gearsystem Accuracy Tests](https://github.com/drhelius/Gearsystem#accuracy-tests) ## External Links - [Official Gearsystem Repository](https://github.com/drhelius/Gearsystem) - [Libretro Gearsystem Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/gearsystem_libretro.info) - [Report Libretro Gearsystem Core Issues Here](https://github.com/drhelius/Gearsystem/issues) ### See also #### Sega - Game Gear - [Sega - MS/GG/MD/CD (Genesis Plus GX)](genesis_plus_gx.md) #### Sega - Master System - Mark III - [Sega - Master System (Emux SMS)](emux_sms.md) - [Sega - MS/GG/MD/CD (Genesis Plus GX)](genesis_plus_gx.md) - [Sega - MS/MD/CD/32X (PicoDrive)](picodrive.md) #### Sega - SG-1000 - [MSX/SVI/ColecoVision/SG-1000 (blueMSX)](bluemsx.md) - [Sega - MS/GG/MD/CD (Genesis Plus GX)](genesis_plus_gx.md) ================================================ FILE: docs/library/genesis_plus_gx.md ================================================ # Sega - MS/GG/MD/CD (Genesis Plus GX) ## Background Genesis Plus GX is an open-source Sega 8/16 bit emulator developed by Eke-Eke which focuses on accuracy and portability. The source code, originally based on Genesis Plus 1.3 by Charles MacDonald, has been heavily modified & enhanced, with respect to initial goals and design, in order to improve the accuracy of emulation, implementing new [features](https://github.com/ekeeke/Genesis-Plus-GX/blob/master/wiki/Features.md) and adding support for [extra peripherals](https://github.com/ekeeke/Genesis-Plus-GX/blob/master/wiki/Features.md#support-for-various-peripherals), [cartridge & systems hardware](https://github.com/ekeeke/Genesis-Plus-GX/blob/master/wiki/Features.md#support-for-various-cartridges-extra-hardware) such as various lightguns, the FM Sound Unit and Lock-On cartridge technology. Genesis Plus GX has [100% compatibility](https://github.com/ekeeke/Genesis-Plus-GX/blob/master/wiki/Compatibility.md) with Genesis / Mega Drive, Sega/Mega CD, Master System, Game Gear, SG-1000 & Pico released software (including all unlicensed or pirate known dumps), also emulating backwards compatibility modes when available. **Keep in mind that [32X games](https://segaretro.org/Sega_32X#List_of_games) are not supported.** The Genesis Plus GX core has been authored by: - Eke-Eke - Charles McDonald The Genesis Plus GX core is licensed under: - [Non-commercial](https://github.com/libretro/Genesis-Plus-GX/blob/master/LICENSE.txt) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS [Required or optional firmware files](https://docs.libretro.com/library/bios/) go in the frontend's system directory: !!! warning "" Please note that BIOS choice isn't locked to any specific revisions. !!! warning "" BIOS files that are labeled (bootrom) and (lock-on) must have their corresponding [core option](#core-options) ('System bootrom' core option or 'Cartridge lock-on' core option) configured correctly in order for them to be loaded. | Filename | Description | md5sum | |:-------------:|:-----------------------------------------------:|:--------------------------------:| | bios_MD.bin | [MegaDrive startup ROM](https://segaretro.org/TradeMark_Security_System) (bootrom) - Optional | 45e298905a08f9cfb38fd504cd6dbc84 | | bios_CD_E.bin | [MegaCD EU BIOS](https://segaretro.org/Sega_Mega-CD/Boot_ROM) - Required for MegaCD EU games | e66fa1dc5820d254611fdcdba0662372 | | bios_CD_U.bin | [SegaCD US BIOS](https://segaretro.org/Sega_Mega-CD/Boot_ROM) - Required for SegaCD US games | 854b9150240a198070150e4566ae1290 | | bios_CD_J.bin | [MegaCD JP BIOS](https://segaretro.org/Sega_Mega-CD/Boot_ROM) - Required for MegaCD JP games | 278a9397d192149e84e820ac621a8edd | | bios_E.sms | [MasterSystem EU BIOS](https://segaretro.org/Sega_Master_System/Boot_ROM) (bootrom) - Optional | 840481177270d5642a14ca71ee72844c | | bios_U.sms | [MasterSystem US BIOS](https://segaretro.org/Sega_Master_System/Boot_ROM) (bootrom) - Optional | 840481177270d5642a14ca71ee72844c | | bios_J.sms | [MasterSystem JP BIOS](https://segaretro.org/Sega_Master_System/Boot_ROM) (bootrom) - Optional | 24a519c53f67b00640d0048ef7089105 | | bios.gg | [GameGear BIOS](https://www.smspower.org/Development/BIOSes#GameGear) (bootrom) - Optional | 672e104c3be3a238301aceffc3b23fd6 | | sk.bin | [Sonic & Knuckles ROM (lock-on)](https://segaretro.org/Sonic_%26_Knuckles/Technical_information) - Optional | 4ea493ea4e9f6c9ebfccbdb15110367e | | sk2chip.bin | [Sonic & Knuckles UPMEM ROM]: [Link 1](https://emulation.gametechwiki.com/index.php/Sega_Genesis_emulators#Lock-On_Emulation); [Link 2](https://info.sonicretro.org/Knuckles_the_Echidna_in_Sonic_the_Hedgehog_2#Functioning) (lock-on) - Optional | b4e76e416b887f4e7413ba76fa735f16 | | areplay.bin | [Action Replay ROM](https://segaretro.org/Action_Replay) (lock-on) - Optional | a0028b3043f9d59ceeb03da5b073b30d | | ggenie.bin | [Game Genie ROM (lock-on)](https://segaretro.org/Game_Genie_(Mega_Drive)) - Optional | e8af7fe115a75c849f6aab3701e7799b | ## Extensions Content that can be loaded by the Genesis Plus GX core have the following file extensions: * .m3u * .mdx * .md * .smd * .gen * .bin * .cue * .iso * .chd * .bms * .sms * .gg * .sg * .68k * .sgd RetroArch database(s) that are associated with the Genesis Plus GX core: - [Sega - Game Gear](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20Game%20Gear.rdb) - [Sega - Master System - Mark III](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20Master%20System%20-%20Mark%20III.rdb) - [Sega - Mega-CD - Sega CD](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20Mega-CD%20-%20Sega%20CD.rdb) - [Sega - Mega Drive - Genesis](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20Mega%20Drive%20-%20Genesis.rdb) - [Sega - PICO](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20PICO.rdb) - [Sega - SG-1000](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20SG-1000.rdb) ## Features Frontend-level settings or features that the Genesis Plus GX core respects: | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✔ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✔ | | Username | ✕ | | Language | ✔ | | Crop Overscan* | ✕ | | LEDs | ✔ | \* Overscan cropping available via the 'Borders' core option instead of frontend-level settings ## Directories The Genesis Plus GX core's library name is 'Genesis Plus GX' The Genesis Plus GX core saves/loads to/from these directories: **Frontend's Save directory** | File | Description | |:------------:|:------------------------------------------------------------------------------------:| | *.srm | [MS/GG/MD/Pico/SG-1000 Cartridge](https://segaretro.org/Cartridge) backup save | | cart.brm | [Sega/Mega CD RAM Cart](https://segaretro.org/CD_BackUp_RAM_Cart) | | scd_U.brm | [Sega CD US Backup RAM](https://segaretro.org/Sega_Mega-CD/Technical_specifications#Memory) - When the [CD System BRAM core option](#system) is set to 'Per-BIOS' | | scd_E.brm | [Mega CD EU Backup RAM](https://segaretro.org/Sega_Mega-CD/Technical_specifications#Memory) - When the [CD System BRAM core option](#system) is set to 'Per-BIOS' | | scd_J.brm | [Mega CD JP Backup RAM](https://segaretro.org/Sega_Mega-CD/Technical_specifications#Memory) - When the [CD System BRAM core option](#system) is set to 'Per-BIOS' | | *.brm | [Sega CD/MegaCD Backup RAM](https://segaretro.org/Sega_Mega-CD/Technical_specifications#Memory) - When the [CD System BRAM core option](#system) is set to 'Per-Game' | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ## Geometry and timing - The Genesis Plus GX core's provided FPS is dependent on the [loaded content](https://github.com/libretro/Genesis-Plus-GX/blob/master/libretro/libretro.c#L3027) - The Genesis Plus GX core's provided sample rate is [44100 Hz](https://github.com/libretro/Genesis-Plus-GX/blob/master/libretro/libretro.c#L199) - The Genesis Plus GX core's base width is dependent on the [loaded content](https://github.com/libretro/Genesis-Plus-GX/blob/master/libretro/libretro.c#L2999) - The Genesis Plus GX core's base height is dependent on the [loaded content](https://github.com/libretro/Genesis-Plus-GX/blob/master/libretro/libretro.c#L3000) - The Genesis Plus GX core's max width is dependent on the [loaded content](https://github.com/libretro/Genesis-Plus-GX/blob/master/libretro/libretro.c#L3001-L3029) - The Genesis Plus GX core's max height is dependent on the [loaded content](https://github.com/libretro/Genesis-Plus-GX/blob/master/libretro/libretro.c#L3001-L3029) - The Genesis Plus GX core's provided aspect ratio is dependent on the 'Core-provided aspect ratio' [core option](#video) ## Loading Sega CD games When loading Sega CD games, Genesis Plus GX needs a cue-sheet that points to an image file. A cue sheet, or cue file, is a metadata file which describes how the tracks of a CD or DVD are laid out. If you have e.g. `foo.bin`, you should create a text file and save it as `foo.cue`. If the Sega CD game is single-track, the cue file contents should look like this: ``` FILE "foo.bin" BINARY TRACK 01 MODE1/2352 INDEX 01 00:00:00 ``` After that, you can load the `foo.cue` file in RetroArch with the Genesis Plus GX core. !!! warning "" Certain Sega CD games are multi-track, so their .cue files might be more complicated. Here's a cue file example done with Lunar - Eternal Blue (USA) ![](../image/core/genesis_plus_gx/cue.png) !!! warning "" For Sega-CD games, ISO + WAV, BIN + CUE and ISO + OGG formats are supported; ISO + MP3 is not supported. Audio files must be in the 16-bit stereo 44100Hz format. If using a cue sheet, WAV or OGG tracks should be denoted as AUDIO. When loading ISO + WAV or ISO + OGG format games, the core will attempt to load a cue named the same as the iso first. If one is not found, the following audio track naming formats are accepted for a data track of "game.iso": - game02.ogg - game 02.ogg - game-02.ogg - game - 02.ogg - game_02.ogg ### Loading Multiple Disk games If foo is a multiple-disk Sega CD game, you should have .cue files for each one, e.g. `foo (Disc 1).cue`, `foo (Disc 2).cue`, `foo (Disc 3).cue`. To take advantage of Genesis Plus GX's Disk Control feature for disk swapping, an index file (a m3u file) should be made. Create a text file and save it as `foo.m3u`. Then enter your game's .cue files on it. The m3u file contents should look something like this: `foo.m3u` ``` foo (Disc 1).cue foo (Disc 2).cue foo (Disc 3).cue ``` After that, you can load the `foo.m3u` file in RetroArch with the Genesis Plus GX core. Here's a m3u example done with the Sega CD 32x version of Night Trap ![](../image/core/genesis_plus_gx/m3u.png) !!! attention Adding multi-track games to a RetroArch playlist is recommended. (Manually add an entry a playlist that points to `foo.m3u`) ### Swapping Disks Disks can be swapped through Quick Menu -> Disk Control in RetroArch. If not using .m3u files, .cue files must be manually selected via the Load New Disk legacy feature. If using .m3u files, disks can be swapped by selecting Eject Disk, changing the Current Disk Index to your desired disk, and finally selecting Insert Disk. ### CHD Alternatively to using cue sheets with .bin/.iso files, you can convert your Sega CD games to .chd (MAME Compressed Hunks of Data) to reduce file sizes and neaten up your game folder. To convert content to CHD format, use the chdman tool found inside the latest MAME distribution and point it to a .cue file, like so: ``` chdman createcd --input foo.cue --output foo.chd ``` !!! attention For multi-disc content, make an .m3u file that lists all the .chd files instead of .cue files (content must be added to playlists manually). ## Playing with MD+ / MSU-MD modes Comparable to how MSU-1 modifcations can enhance SNES games; Mega Drive Plus / Genesis Plus (MD+) and MSU-MD (Mega SD flash cartridge) patches can be used to add CD quality level of audio to certain Sega Genesis and Mega Drive games via the emulated Sega CD hardware and its CDDA track functionality. Regarding Genesis Plus GX's implementation of MD+ mode operation, all CD overlay commands (incl. cue loop commands) described in MegaSD dev manual (see referenced PDF at the end of this section) are supported except the ones that deal with opening/reading files from SD card (starting from command 1Ch) but afaik no MD+ hacks use these commands so far. Since there is no way to auto-detect a MD+ patched ROM, MegaSD add-on emulation needs to be enabled in core options (through the newly added "CD add-on" core option). However, when "CD add-on" core option is set to Auto, if a cue file with same basename as loaded ROM file is found in same directory AND that cue file contains MegaSD specific keywords ("REM LOOP xxx", "REM NOLOOP",...), MegaSD CD overlay emulation will be automatically enabled (instead of full Sega/Mega CD hardware emulation). By setting the "CD add-on" core option to "Sega/Mega CD", you can force Sega/Mega CD hardware emulation when any MD game (<8MB) is loaded even if there is no cue file found in loaded game directory (this can be useful for demos or homebrew games that want to use Mega CD extra hardware without necessarily having a loaded CD beforehand). And by setting the "CD add-on" option to "None", Sega/Mega CD hardware emulation will be forced disabled, even if a cue file is found in loaded game directory or when the loaded game is known to have Sega/Mega CD support (like Pier Solar, Flux or Wonder Library). This emulates the behavior where there is no Sega/Mega CD unit attached. Although no known games are using them, MegaSD extended SSF2 mapper and limited ROM write mapper (automatically enabled when respectively "SEGA SSF2" and "SEGA MEGASD" are found in loaded ROM header) are also emulated, according to the description in MegaSD dev manual. Note that MegaSD overlay will also automatically be enabled when these mappers are detected, no matter of the "CD Add-on" core option. Please peruse the official MegaSD manual for further information: https://downloads.terraonion.com/public/MegaSD_DEV_Manual.pdf Also, there's an useful reference wiki here for MSU-MD games/patches and its technical specifications here: https://arcadetv.github.io/msu-md-patches/ !!! attention Make sure that your files match what's specified in your MD+/MSU-MD cue file! ## Core options The Genesis Plus GX core has the following options that can be tweaked from your frontend's core options menu or manually changed via core configuration files. Options are listed below in the following format: Option Name [option_key] (setting1/setting2/...) To manually change an option, search for that option's key in the core configuration file you want to edit and set it to your desired setting value, enclosed in quotations. For example, if you had set the CD-DA Volume to 50% and wanted to revert it to 100%, you would change genesis_plus_gx_cdda_volume = "50" to genesis_plus_gx_cdda_volume = "100". Manually editing core configuration files is typically unnecessary unless your frontend does not have a method for toggling options. The default setting for each option will be highlighted in **bold**. Settings with (Restart) means that core has to be shut down for the new setting to be applied on next launch. ### System Configure base hardware selection / region / BIOS / Sega CD save file parameters. _________________ **System hardware** [genesis_plus_gx_system_hw] Runs loaded content with a specific emulated console. * **Auto [auto]** Loads the game with the most appropriate system based on the loaded [game's ROM information](https://github.com/libretro/Genesis-Plus-GX/blob/master/core/loadrom.c) like its ROM type, product code/version, checksum, size and region code. * SG-1000 [sg-1000 II] - Loads game with the [SG-1000 console](https://segaretro.org/SG-1000). * SG-1000 II + RAM Ext. [sg-1000 II + ram ext.] - Loads game with the [SG-1000 II console](https://segaretro.org/SG-1000_II) with a [RAM extension adapter](https://segaretro.org/8kB_RAM_Adapter). * Mark III [mark-III] - Loads game with the [Mark III console](https://segaretro.org/Sega_Mark_III) * Master System [master system] - Loads game with the [Master System console](https://segaretro.org/Sega_Master_System#Master_System) * Master System II [master system II] - Loads game with the [Master System II console](https://segaretro.org/Sega_Master_System#Master_System_II) * Game Gear [game gear] - Loads game with the [Game Gear handheld console](https://segaretro.org/Sega_Game_Gear) * Mega Drive/Genesis [mega drive / genesis] - Loads game with the [Mega Drive/Genesis console](https://segaretro.org/Sega_Mega_Drive) **System region** [genesis_plus_gx_region_detect] Specify which region the system is from. For consoles other than the Game Gear, PAL is 50hz while NTSC is 60hz. Games may run faster or slower than normal if the incorrect region is selected. * **Auto [auto]** - Changes the system's region to whatever is most appropriate for the game which is based on the loaded [game's ROM information](https://github.com/libretro/Genesis-Plus-GX/blob/master/core/loadrom.c) like its ROM type, product code/version, checksum, size and region code. * NTSC-U [ntsc-u] - Changes the system's region to [NTSC-U](https://en.wikipedia.org/wiki/NTSC). * PAL [pal] - Changes the system's region to [PAL](https://en.wikipedia.org/wiki/PAL_region). * NTSC-J [ntsc-j] - Changes the system's region to [NTSC-J](https://en.wikipedia.org/wiki/NTSC-J). **System Boot ROM** [genesis_plus_gx_bios] (**disabled**/enabled) Use official BIOS/bootloader for emulated hardware, if present in RetroArch's system directory. Displays console-specific start-up sequence/animation, then runs loaded content. Look above at the [BIOS section](#bios) for supported BIOS types/files. * **Off [disabled]** - Disables using the user supplied System Boot ROM. * On [enabled] - Enables using the user supplied System Boot ROM. **CD System BRAM** [genesis_plus_gx_system_bram] When running Sega CD content, specifies whether to share a single save file between all games from a specific region (Per-BIOS) or to create a separate save file for each game (Per-Game). Note that the Sega CD has [limited internal storage](https://segaretro.org/Sega_Mega-CD/Technical_specifications#Memory), sufficient only for a handful of titles. To avoid running out of space, the 'Per-Game' setting is recommended. * **Per-BIOS [per bios]** - All games from a specific region share a single save file. * Per-Game [per game] - Creates a separate save file for each game. ??? note "*CD System BRAM diagram*" ![](../image/core/genesis_plus_gx/bram.png) **CD Backup Cart BRAM** [genesis_plus_gx_cart_bram] When running Sega CD content, specifies whether to share a single backup [ram cart](https://segaretro.org/CD_BackUp_RAM_Cart) for all games (Per-Cart) or to create a separate backup ram cart for each game (Per-Game). * **Per-Cart [per cart]** - All games share a single backup RAM cart. * Per-Game [per game] - Creates a seperate backrup RAM cart for each game. **CD add-on (MD mode) (Requires Restart)** [genesis_plus_gx_add_on] Specify which add-on to use for CD audio playback with supported Mega Drive/Genesis games. * **Auto [auto]** - Loads a CD game with the most appropriate CD add-on based on the loaded [game's ROM information](https://github.com/libretro/Genesis-Plus-GX/blob/master/core/loadrom.c) like its ROM type, product code/version, checksum, size and region code. (when "CD add-on" core option is set to Auto, if a cute file with same basename as loaded ROM file is found in same directory AND that cue file contains MegaSD specific keywords ("REM LOOP xxx", "REM NOLOOP",...), MegaSD CD overlay emulation will be automatically enabled (instead of full Sega/Mega CD hardware emulation)) * Sega/Mega CD [sega/mega cd] - Loads the game using the [Sega/Mega CD add-on](https://segaretro.org/Sega_Mega-CD). (this can be useful for demos or homebrew games that want to use Mega CD extra hardware without necessarily having a loaded CD beforehand since it forces Sega/Mega CD hardware emulation when any MD game (<8MB) is loaded even if there is no CUE file found in loaded game directory) * MegaSD [megasd] - Loads the game using the [MegaSD FPGA cartridge](https://wiki.terraonion.com/index.php/MegaSD). Look at the # section for more information. * None [none] - Disables loading a CD game with any CD add-on. (Sega/Mega CD hardware emulation will be forced disabled, even if a CUE file is found in loaded game directory or when the loaded game is known to have Sega/Mega CD support (like Pier Solar, Flux or Wonder Library). This emulates the behavior where there is no Sega/Mega CD unit attached.) **Cartridge Lock-On** [genesis_plus_gx_lock_on] Lock-On Technology is a Mega Drive/Genesis feature that allowed an older game to connect to the pass-through port of a special cartridge for extended or altered gameplay. This option specifies which type of special 'lock-on' cartridge to emulate. Look above at the [BIOS section](#bios) for supported BIOS types/files. * **Off [disabled]** * Game Genie [game genie] - Connects the loaded game to a [Gamie Genie](https://segaretro.org/Game_Genie_(Mega_Drive)). * Action Replay (Pro) [action replay (pro)] - Connects the loaded game to an [Action Replay (Pro)](https://segaretro.org/Action_Replay). * Sonic & Knuckles [sonic & knuckles)] - Connects the loaded game to [Sonic & Knuckles](https://info.sonicretro.org/Sonic_%26_Knuckles). ### Video Configure aspect ratio / display cropping / video filter / frame skipping parameters. _________________ **Core-Provided Aspect Ratio** [genesis_plus_gx_aspect_ratio] Choose the preferred content aspect ratio. This will only apply when RetroArch's aspect ratio is set to 'Core provided' in the Video settings. * **Auto [auto]** - Chooses the aspect ratio based on the loaded [game's ROM information](https://github.com/libretro/Genesis-Plus-GX/blob/master/core/loadrom.c) like its ROM type, product code/version, checksum, size and region code. * NTSC PAR [NTSC PAR] - Sets the game's aspect ratio to NTSC PAR. * PAL PAR [PAL PAR] - Sets the game's aspect ratio to PAL PAR. **Borders** [genesis_plus_gx_overscan] Enable this to display the overscan regions at the top/bottom and/or left/right of the screen. These would normally be hidden by the bezel around the edge of a standard-definition television. * **Off [disabled]** - Disables displaying the game's overscan regions. * Top/Bottom [top/bottom] - Enables displaying the game's Top and Bottom overscan regions. * Left/Right [left/right] - Enables displaying the game's Left and Right overscan regions. * Full [full] - Enables displaying the game's Top/Bottom and Left/Right overscan regions. **Hide Master System Side Borders** [genesis_plus_gx_left_border] Cuts off 8 pixels from either the left side of the screen, or both left and right sides when running Master System games. * **Off [disabled]** - Disabling cutting off pixels from the screen of a Master System game. * Left Border Only [left border] - Cuts off 8 pixels from the left side of the screen of a Master System game. * Left & Right Borders [left & right borders] - Cuts off 8 pixels from the right side of the screen of a Master System game. **Game Gear Extended Screen** [genesis_plus_gx_gg_extra] Forces Game Gear titles to run in 'SMS' mode, with an increased resolution of 256x192. May show additional content, but typically displays a border of corrupt/unwanted image data. ??? note "*Off [disabled]*" ![](../image/core/genesis_plus_gx/off.png) ??? note "*On [enabled]*" ![](../image/core/genesis_plus_gx/on.png) **Blargg NTSC Filter** [genesis_plus_gx_blargg_ntsc_filter] - Apply a video filter to mimic various NTSC TV signals. ??? note "*Disabled vs All Filters (video)*" https://youtu.be/buZPDyDzvPY ??? note "*Off [disabled]*" ![](../image/core/genesis_plus_gx/normal.png) ??? note "*Monochrome [monochrome]*" ![](../image/core/genesis_plus_gx/monochrome.png) ??? note "*Composite [composite]*" ![](../image/core/genesis_plus_gx/composite.png) ??? note "*S-Video [svideo]*" ![](../image/core/genesis_plus_gx/svideo.png) ??? note "*RGB [rgb]*" ![](../image/core/genesis_plus_gx/rgb.png) **LCD Ghosting Filter** [genesis_plus_gx_lcd_filter] Apply an image 'ghosting' filter to mimic the display characteristics of the Game Gear and 'Genesis Nomad' LCD panels. * **Off** [disabled] - Disables ghosting filter. * On [enabled] - Enables ghosting filter. ??? note "*Disabled vs Enabled (video)*" https://youtu.be/Us13sJPEUD8 ??? note "*Enabled*" ![](../image/core/genesis_plus_gx/ghost.png) **Interlaced Mode 2 Output** [genesis_plus_gx_render] Interlaced Mode 2 allows the Mega Drive/Genesis to output a double height (high resolution) 320x448 image by drawing alternate scanlines each frame (this is used by 'Sonic the Hedgehog 2' and 'Combat Cars' multiplayer modes). 'Single Field' mimics original hardware, producing each field (320x224) alternatively with flickering/interlacing artefacts. 'Double Field' simulates the interlaced display, which stabilises the image but causes mild blurring. * **Single Field** [single field] - Sets Interlaced Mode 2 Output as Single Field. * Double Field [double field] - Sets Interlaced Mode 2 Output as Double Field. ??? note "*Single Field vs Double Field (video)*" https://youtu.be/xZc58OSPj4Y ??? note "*Single Field*" ![](../image/core/genesis_plus_gx/single.png) ??? note "*Double Field*" ![](../image/core/genesis_plus_gx/double.png) **Frameskip** [genesis_plus_gx_frameskip] Skip frames to avoid audio buffer under-run (crackling). Improves performance at the expense of visual smoothness. 'Auto' skips frames when advised by the frontend. 'Manual' utilises the 'Frameskip Threshold (%)' setting. * **Off [disabled]** - Disables frameskip. * Auto [auto] - Automatically skips frames to avoid audio crackling. * Manual [manual] - Allows the user to utilises the 'Frameskip Threshold' core option's set percentage to manually adjust frameskip. **Frameskip Threshold (%)** [genesis_plus_gx_frameskip_threshold] When the 'Frameskip' core option is set to 'Manual', specifies the audio buffer occupancy threshold (percentage) below which frames will be skipped. Higher values reduce the risk of crackling by causing frames to be dropped more frequently. : 15% to 60% in increments of 3%, **33% is default**. ### Audio Change audio device settings. _________________ **Master System FM (YM2413)** [genesis_plus_gx_ym2413] Enable emulation of the [FM Sound Unit](http://segaretro.org/FM_Sound_Unit) used by certain Sega Mark III/Master System games for enhanced audio output. * **Auto [auto]** - Automatically enables emulation of FM Sound Unit based on the loaded [game's ROM information](https://github.com/libretro/Genesis-Plus-GX/blob/master/core/loadrom.c) like its ROM type, product code/version, checksum, size and region code. * Off [disabled] - Manually disables emulation of FM Sound Unit. * On [enabled] - Manually enables emulation of FM Sound Unit. **Master System FM (YM2413) Core** - [genesis_plus_gx_ym2413_core] Select method used to emulate the [FM Sound Unit](https://segaretro.org/FM_Sound_Unit) of the Sega Mark III/Master System. 'MAME' option is fast, and runs full speed on most systems. 'Nuked' option is cycle accurate, very high quality, and has substantial CPU requirements. * **MAME [mame]** - Uses the MAME option for emulating the FM Sound Unit for Sega Mark III/Master System games which is fast and full speed for most games. * Nuked [nuked] - Uses the Nuked option for emulating the FM Sound Unit for Sega Mark III/Master System games which is high quality but has substantial CPU requirements. **Mega Drive/Genesis FM** [genesis_plus_gx_ym2612] Select method used to emulate the FM synthesizer (main sound generator) of the Mega Drive/Genesis. 'MAME' options are fast, and run full speed on most systems. 'Nuked' options are cycle accurate, very high quality, and have substantial CPU requirements. The ['YM2612'](https://segaretro.org/YM2612) chip is used by the original Model 1 Mega Drive/Genesis. The ['YM3438'](https://segaretro.org/index.php?title=YM3438&redirect=no) is used in later Mega Drive/Genesis revisions. * **MAME (YM2612) [mame (ym2612)]** - Selects MAME (YM2612) [original Model 1 Mega Drive/Genesis] as FM synthesizer method which is fast and fullspeed. * MAME (ASIC YM3438) [mame (asic ym3438)] - Selects MAME (ASIC YM3438) [later Mega Drive/Genesis revisions] as FM synthesizer method which is fast and fullspeed. * MAME (Enhanced YM3438) [mame (enhanced ym3438)] - Selects MAME (Enhanced YM3438) [later Mega Drive/Genesis revisions] as FM synthesizer method which is fast and fullspeed. * Nuked (YM2612) [nuked (ym2612)] - Selects Nuked (YM2612) [original Model 1 Mega Drive/Genesis] as FM synthesizer method which is high quality but has high CPU requirements. * Nuked (YM3438) [nuked (ym3438)] - Selects Nuked (YM3438) [later Mega Drive/Genesis revisions] FM synthesizer method which is fast but has high CPU requirements. **Sound Output** [genesis_plus_gx_sound_output] Select stereo or mono sound reproduction. * **Stereo [stereo]** - Selects stereo output. * Mono (mono) - Selects mono output. **Audio Filter** [genesis_plus_gx_audio_filter] Enable a low pass audio filter to better simulate the characteristic sound of a Model 1 Mega Drive/Genesis. * **Off [disabled]** - Disables low pass audio filter. * Low-Pass [low-pass] - Enables low pass audio filter. * EQ [EQ] - Enables internal audio equalizer. **Low-Pass Filter %** [genesis_plus_gx_lowpass_range] Specify the cut-off frequency of the low-pass audio filter. A higher value increases the perceived 'strength' of the filter, since a wider range of the high frequency spectrum is attenuated. This core option requires the 'Audio Filter' core option to be set to 'Low-Pass". * 5% to 95% in increments of 5. *60% is default**. **PSG Preamp Level** [genesis_plus_gx_psg_preamp] Set the audio preamplifier level of the emulated SN76496 4-channel Programmable Sound Generator found in the [SG-1000](https://segaretro.org/SG-1000#Sound), [Sega Mark III](https://segaretro.org/Sega_Mark_III#Sound), [Master System](https://segaretro.org/Sega_Master_System/Technical_specifications#Audio), [Game Gear](https://segaretro.org/Sega_Game_Gear#Technical_specifications) and [Mega Drive/Genesis](https://segaretro.org/Sega_Mega_Drive/Technical_specifications#Audio). * 0 to 200 in increments of 5. **150 is default**. **FM Preamp Level** [genesis_plus_gx_fm_preamp] Set the audio preamplifier level of the emulated [Mega Drive/Genesis FM sound synthesizer](https://segaretro.org/Sega_Mega_Drive/Technical_specifications#Audio) or [Sega Mark III/Master System FM Sound Unit](https://segaretro.org/FM_Sound_Unit). * 0 to 200 in increments of 5. **100 is default**. **CD-DA Volume** [genesis_plus_gx_cdda_volume] Adjust the mixing volume of the emulated [CD audio](https://segaretro.org/Sega_Mega-CD/Technical_specifications#Audio) playback output. * 0 to 100 in increments of 5. **100 is default**. **PCM Volume** [genesis_plus_gx_pcm_volume] - Adjust the mixing volume of the emulated [Sega CD/Mega-CD RF5C164 PCM](https://segaretro.org/Sega_Mega-CD/Technical_specifications#Audio) sound generator output. * 0 to 100 in increments of 5. **100 is default**. **EQ Low** [genesis_plus_gx_audio_eq_low] Adjust the low range band of the internal audio equalizer. * 0 to 100 in increments of 5. **100 is default**. **EQ Mid** [genesis_plus_gx_audio_eq_mid] Adjust the mid range band of the internal audio equalizer. * 0 to 100 in increments of 5. **100 is default**. **EQ High** [genesis_plus_gx_audio_eq_high] Adjust the high range band of the internal audio equalizer. * 0 to 100 in increments of 5. **100 is default**. ### Input _________________ Change light gun and/or mouse input settings. **Light Gun Input** [genesis_plus_gx_gun_input] Use a mouse-controlled 'Light Gun' or 'Touchscreen' input. * **Light Gun [lightgun]** - Selects mouse-controlled 'Light Gun' input (devices will use [RetroLightgun](#lightgun) inputs). * Touchscreen [touchscreen] - Allows the [MS Light Phaser, MD Menancer and MD Justifiers](#lightgun) device types to be controlled via touchscreen input (devices will use [RetroPointer](#pointer) inputs instead). **Show Light Gun Crosshair** [genesis_plus_gx_gun_cursor] Display light gun crosshairs when using the [MD Menacer, MD Justifiers and MS Light Phaser](#lightgun) input device types. * **Off [disabled]** - Disables light gun crosshair for the aftermentioned input device types. * On [enabled] - Enables light gun crosshair for the aftermentioned input device types. ??? note "*Disabled vs Enabled (video)*" https://www.youtube.com/watch?v=w6iYysbni2g **Invert Mouse Y-Axis** [genesis_plus_gx_invert_mouse] Inverts the Y-axis of the ['MD Mouse'](#mouse) input device type. * **Off [disabled]** - Enables Y-Axis inversion for the 'MD Mouse' device type. * On [enabled] - Disables Y-Axis inversion for the 'MD Mouse' device type. ### Emulation Hacks _________________ Change processor overclocking and emulation accuracy settings that affect low-level performance and compatibility. **Remove Per-Line Sprite Limit** [genesis_plus_gx_no_sprite_limit] Removes the original sprite-per-scanline hardware limit. This reduces flickering but can cause visual glitches, as some games exploit the hardware limit to generate special effects. * **Off [disabled]** - Keeps the per-line sprite limit. * On [enabled] - Disables the per-line sprite limit. ??? note "*Disabled vs Enabled (video)*" https://youtu.be/IZp5epy-hBM **Enhanced per-tile vertical scroll** [genesis_plus_gx_enhanced_vscroll] Allows each individual cell to be scrolled vertically, instead of 16px 2-cell, by averaging out with the vscroll value of the neighbouring cell. This hack only applies to few games that use 2-cell vertical scroll mode. * **Off [disabled]** - Enables enhanced per-tile vertical scrolling. * On [enabled] - Disables enhanced per-tile vertical scrolling. ??? note "*Disabled*" ![](../image/core/genesis_plus_gx/vertical_disabled.png) ??? note "*Enabled [16]*" ![](../image/core/genesis_plus_gx/vertical_enabled.png) **Enhanced per-tile vertical scroll limit** [genesis_plus_gx_enhanced_vscroll_limit] Only is usable when the 'Enhanced per-tile vertical scroll' core option is enabled. Adjusts the limit of the vertical scroll enhancement. When the vscroll difference between neighbouring tiles is bigger than this limit, the enhancement is disabled. * 2 to 16 in increments of 1. **8 is default** **CPU Speed** [genesis_plus_gx_overclock] Overclock the emulated CPU. Can reduce slowdown, but may cause glitches. * 100% to 500% in increments of 25%. **100% is default.** ??? note "*!00% vs 200% (video)*" https://youtu.be/yE8qzwVuy5Q **System Locks-Ups** [genesis_plus_gx_force_dtack] Emulate system lock-ups that occur on real hardware when performing illegal address access. This should only be disabled when playing certain demos, homebrew and ROM hacks that rely on illegal behavior for correct operation. * **On [enabled]** - Enables emulation of system lock-ups. * Off [disabled] - Disables emulation of system lock-ups. ??? note "*Enabled vs Disabled (video)*" https://youtu.be/B1n1wQGzzYk **68K Address Error** [genesis_plus_gx_addr_error] The [Mega Drive/Genesis main CPU (Motorola 68000)](http://segaretro.org/M68000) generates an Address Error exception (crash) when attempting to perform unaligned memory access. Enabling this will simulate this behavior. It should only be disabled when playing ROM hacks, since these are typically developed using less accurate emulators and may rely on invalid RAM access for correct operation. * **On [enabled]** - Enables simulation of 68K Address Error. * Off [disabled] - Disables simulation of 68K Address Error. ??? note "*Enabled vs Disabled (video)*" https://youtu.be/zjBPz9QWRqI ??? note "*Enabled*" ![](../image/core/genesis_plus_gx/address_error.png) **CD access time** [genesis_plus_gx_cd_latency] Simulate [original CD hardware latency](https://segaretro.org/Sega_Mega-CD/Technical_specifications#Storage) when initiating a read or seeking to a specific location on loaded disc. This is required by a few CD games that crash if CD data is available too soon and also fixes CD audio desync issues in some games. Disabling this can be useful with [MD+ or MSU-MD games](https://emulation.gametechwiki.com/index.php/Sega_Genesis_emulators#Mega_Drive_Plus_.2F_Genesis_Plus_.2F_MSU-MD_modes) as it makes CD audio tracks loops more seamless. * **On [enabled]** - Enables simulation of original CD hardware latency. * Off [disabled] - Disables simulation of original CD hardware latency. ### Advanced Channel Volume Settings _________________ Change the volume of individual hardware audio channels. **Show Advanced Audio Volume Settings (Reopen menu)** [genesis_plus_gx_show_advanced_audio_settings] Enable configuration of low-level audio channel parameters core options listed below. NOTE: Quick Menu must be toggled for this setting to take effect. * **On [enabled]** - Enables configuration of low-level audio channel parameters. * Off [disabled] - Disables configuration of low-level audio channel parameters. **PSG Tone Channel 0 Volume %** [genesis_plus_gx_psg_channel_0_volume] Adjust the volume of Channel 0 of the [PSG Tone](https://segaretro.org/Sega_Mega_Drive/Technical_specifications#Audio). * 0% to 100% in increments of 10%. **100% is default**. **PSG Tone Channel 1 Volume %** [genesis_plus_gx_psg_channel_1_volume] Adjust the volume of Channel 1 of the [PSG Tone](https://segaretro.org/Sega_Mega_Drive/Technical_specifications#Audio). * 0% to 100% in increments of 10%. **100% is default**. **PSG Tone Channel 2 Volume %** [genesis_plus_gx_psg_channel_2_volume] Adjust the volume of Channel 2 of the [PSG Tone](https://segaretro.org/Sega_Mega_Drive/Technical_specifications#Audio). * 0% to 100% in increments of 10%. **100% is default**. **PSG Tone Channel 3 Volume %** [genesis_plus_gx_psg_channel_3_volume] Adjust the volume of Channel 3 of the [PSG Tone](https://segaretro.org/Sega_Mega_Drive/Technical_specifications#Audio). * 0% to 100% in increments of 10%. **100% is default**. **Mega Drive/Genesis FM Channel 0 Volume %** [genesis_plus_gx_md_channel_0_volume] Adjust the volume of Channel 0 of the [Mega Drive/Genesis FM](https://segaretro.org/Sega_Mega_Drive/Technical_specifications#Audio). Only works with MAME FM emulators ('Mega Drive/Genesis FM' core option). * 0% to 100% in increments of 10%. **100% is default**. **Mega Drive/Genesis FM Channel 1 Volume %** [genesis_plus_gx_md_channel_1_volume] Adjust the volume of Channel 1 of the [Mega Drive/Genesis FM](https://segaretro.org/Sega_Mega_Drive/Technical_specifications#Audio). Only works with MAME FM emulators ('Mega Drive/Genesis FM' core option). * 0% to 100% in increments of 10%. **100% is default**. **Mega Drive/Genesis FM Channel 2 Volume %** [genesis_plus_gx_md_channel_2_volume] Adjust the volume of Channel 2 of the [Mega Drive/Genesis FM](https://segaretro.org/Sega_Mega_Drive/Technical_specifications#Audio). Only works with MAME FM emulators ('Mega Drive/Genesis FM' core option). * 0% to 100% in increments of 10%. **100% is default**. **Mega Drive/Genesis FM Channel 3 Volume %** [genesis_plus_gx_md_channel_3_volume] Adjust the volume of Channel 3 of the [Mega Drive/Genesis FM](https://segaretro.org/Sega_Mega_Drive/Technical_specifications#Audio). Only works with MAME FM emulators ('Mega Drive/Genesis FM' core option). * 0% to 100% in increments of 10%. **100% is default**. **Mega Drive/Genesis FM Channel 4 Volume %** [genesis_plus_gx_md_channel_4_volume] Adjust the volume of Channel 4 of the [Mega Drive/Genesis FM](https://segaretro.org/Sega_Mega_Drive/Technical_specifications#Audio). Only works with MAME FM emulators ('Mega Drive/Genesis FM' core option). * 0% to 100% in increments of 10%. **100% is default**. **Mega Drive/Genesis FM Channel 5 Volume %** [genesis_plus_gx_md_channel_5_volume] Adjust the volume of Channel 5 of the [Mega Drive/Genesis FM](https://segaretro.org/Sega_Mega_Drive/Technical_specifications#Audio). Only works with MAME FM emulators ('Mega Drive/Genesis FM' core option). * 0% to 100% in increments of 10%. **100% is default**. **Master System FM (YM2413) Channel 0 Volume %** [genesis_plus_gx_sms_fm_channel_0_volume] Adjust the volume of Channel 0 of the [Master System FM](https://segaretro.org/Sega_Master_System/Technical_specifications#Audio). * 0% to 100% in increments of 10%. **100% is default**. **Master System FM (YM2413) Channel 1 Volume %** [genesis_plus_gx_sms_fm_channel_1_volume] Adjust the volume of Channel 1 of the [Master System FM](https://segaretro.org/Sega_Master_System/Technical_specifications#Audio). * 0% to 100% in increments of 10%. **100% is default**. **Master System FM (YM2413) Channel 2 Volume %** [genesis_plus_gx_sms_fm_channel_2_volume] Adjust the volume of Channel 2 of the [Master System FM](https://segaretro.org/Sega_Master_System/Technical_specifications#Audio). * 0% to 100% in increments of 10%. **100% is default**. **Master System FM (YM2413) Channel 3 Volume %** [genesis_plus_gx_sms_fm_channel_3_volume] Adjust the volume of Channel 3 of the [Master System FM](https://segaretro.org/Sega_Master_System/Technical_specifications#Audio). * 0% to 100% in increments of 10%. **100% is default**. **Master System FM (YM2413) Channel 4 Volume %** [genesis_plus_gx_sms_fm_channel_4_volume] Adjust the volume of Channel 4 of the [Master System FM](https://segaretro.org/Sega_Master_System/Technical_specifications#Audio). * 0% to 100% in increments of 10%. **100% is default**. **Master System FM (YM2413) Channel 5 Volume %** [genesis_plus_gx_sms_fm_channel_5_volume] Adjust the volume of Channel 5 of the [Master System FM](https://segaretro.org/Sega_Master_System/Technical_specifications#Audio). * 0% to 100% in increments of 10%. **100% is default**. **Master System FM (YM2413) Channel 6 Volume %** [genesis_plus_gx_sms_fm_channel_6_volume] Adjust the volume of Channel 6 of the [Master System FM](https://segaretro.org/Sega_Master_System/Technical_specifications#Audio). * 0% to 100% in increments of 10%. **100% is default**. **Master System FM (YM2413) Channel 7 Volume %** [genesis_plus_gx_sms_fm_channel_7_volume] Adjust the volume of Channel 7 of the [Master System FM](https://segaretro.org/Sega_Master_System/Technical_specifications#Audio). * 0% to 100% in increments of 10%. **100% is default**. **Master System FM (YM2413) Channel 8 Volume %** [genesis_plus_gx_sms_fm_channel_8_volume] Adjust the volume of Channel 8 of the [Master System FM](https://segaretro.org/Sega_Master_System/Technical_specifications#Audio). * 0% to 100% in increments of 10%. **100% is default**. ## User 1 device types The Genesis Plus GX core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): - Joypad Port Empty - None - No device is connected; input is disabled. - **Joypad Auto** - Joypad - Depending on the loaded [game's ROM information](https://github.com/libretro/Genesis-Plus-GX/blob/master/core/loadrom.c), the core will automatically emulate a MD Joypad 3 Button controller, or a MD Joypad 6 Button controller or a MS Joypad 2 Button controller. - [MD Joypad 3 Button](https://segaretro.org/Control_Pad_(Mega_Drive)) - Joypad - [MD Joypad 6 Button](https://segaretro.org/Six_Button_Control_Pad_(Mega_Drive)) - Joypad - [MS Joypad 2 Button](https://segaretro.org/Control_Pad_(Master_System)) - Joypad - Also used for Game Gear. - [MD Joypad 3 Button + 4-WayPlay](https://segaretro.org/4_Way_Play) - Joypad - Enables multitap for 4-WayPlay games. - [MD Joypad 6 Button + 4-WayPlay](https://segaretro.org/4_Way_Play) - Joypad - Enables multitap for 4-WayPlay games. - [MD Joypad 3 Button + Teamplayer](https://segaretro.org/Team_Player) - Joypad - Enables multitap for Teamplayer games. - [MD Joypad 6 Button + Teamplayer](https://segaretro.org/Team_Player) - Joypad - Enables multitap for Teamplayer games. - MS Joypad 2 Button + Master Tap - Joypad - Enables [Furrtek's Master Tap](https://www.smspower.org/Homebrew/BOoM-SMS) (unofficial mulitap device). - [MS Light Phaser](https://segaretro.org/Light_Phaser) - Lightgun - [MS Paddle Control](https://segaretro.org/Paddle_Control) - Analog - [MS Sports Pad](https://segaretro.org/Sports_Pad) - Analog - [MS Graphic Board](https://segaretro.org/Sega_Graphic_Board) - Pointer - [MD XE-1AP](https://segaretro.org/XE-1_AP) - Analog - [MD Mouse](https://segaretro.org/Sega_Mouse) - Mouse ## User 2 device types - Joypad Port Empty - None - No device is connected; input is disabled. - **Joypad Auto** - Joypad - Depending on the loaded [game's ROM information](https://github.com/libretro/Genesis-Plus-GX/blob/master/core/loadrom.c), the core will automatically emulate a MD Joypad 3 Button controller, or a MD Joypad 6 Button controller or a MS Joypad 2 Button controller. - [MD Joypad 3 Button](https://segaretro.org/Control_Pad_(Mega_Drive)) - Joypad - [MD Joypad 6 Button](https://segaretro.org/Six_Button_Control_Pad_(Mega_Drive)) - Joypad - [MS Joypad 2 Button](https://segaretro.org/Control_Pad_(Master_System)) - Joypad - Also used for Game Gear. - [MD Joypad 3 Button + 4-WayPlay](https://segaretro.org/4_Way_Play) - Joypad - Enables multitap for 4-WayPlay games. - [MD Joypad 6 Button + 4-WayPlay](https://segaretro.org/4_Way_Play) - Joypad - Enables multitap for 4-WayPlay games. - [MD Joypad 3 Button + Teamplayer](https://segaretro.org/Team_Player) - Joypad - Enables multitap for Teamplayer games. - [MD Joypad 6 Button + Teamplayer](https://segaretro.org/Team_Player) - Joypad - Enables multitap for Teamplayer games. - MS Joypad 2 Button + Master Tap - Joypad - Enables [Furrtek's Master Tap](https://www.smspower.org/Homebrew/BOoM-SMS) (unofficial mulitap device). - [MD Menancer](https://segaretro.org/Menacer) - Lightgun - [MD Justifiers](https://segaretro.org/The_Justifier) - Lightgun - [MS Light Phaser](https://segaretro.org/Light_Phaser) - Lightgun - [MS Paddle Control](https://segaretro.org/Paddle_Control) - Analog - [MS Sports Pad](https://segaretro.org/Sports_Pad) - Analog - [MS Graphic Board](https://segaretro.org/Sega_Graphic_Board) - Pointer - [MD XE-1AP](https://segaretro.org/XE-1_AP) - Analog - [MD Mouse](https://segaretro.org/Sega_Mouse) - Mouse ## Other devices - [PICO tablet](https://segaretro.org/Sega_Pico) - The Genesis Plus GX core can emulate PICO tablet inputs but this is done automatically; based on the loaded [game's ROM information](https://github.com/libretro/Genesis-Plus-GX/blob/master/core/loadrom.c) and cannot be manually selected as a device type. - [Terebi Oekaki tablet](https://segaretro.org/Terebi_Oekaki) - The Genesis Plus GX core can emulate Terebi Oekaki table inputs but this is done automatically; based on the loaded [game's ROM information](https://github.com/libretro/Genesis-Plus-GX/blob/master/core/loadrom.c) and cannot be manually selected as a device type. ## Multitap Activating multitap support in compatible games can be configured by the 4-WayPlay, Teamplayer or Master Tap device types for the [User 1](#user-1-device-types) and/or [User 2](#user-2-device-types) ports. ## Joypad | RetroPad Inputs | User 1 - 8 input descriptors | [MD Joypad 3 Button](https://segaretro.org/Control_Pad_(Mega_Drive)) | [MD Joypad 6 Button](https://segaretro.org/Six_Button_Control_Pad_(Mega_Drive)) | [MS Joypad 2 Button](https://segaretro.org/Control_Pad_(Master_System)) | [MS Paddle Control](https://segaretro.org/Paddle_Control) | [MS Sports Pad](https://segaretro.org/Sports_Pad) | [MD XE-1AP](https://segaretro.org/XE-1_AP) | |------------------------------------------------|------------------------------|--------------------|--------------------|--------------------|-------------------|---------------|---------------| | ![](../image/retropad/retro_b.png) | B | B | B | 1 | 1 | 1 | E2 | | ![](../image/retropad/retro_y.png) | A | A | A | | | | E1 | | ![](../image/retropad/retro_select.png) | Mode | | Mode | | | | Select | | ![](../image/retropad/retro_start.png) | Start | Start | Start | Start | Start | Start | Start | | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | D-Pad Up | D-Pad Up | D-Pad Up | | | | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | D-Pad Down | D-Pad Down | D-Pad Down | | | | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | D-Pad Left | D-Pad Left | D-Pad Left | | | | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | D-Pad Right | D-Pad Right | D-Pad Right | | | | | ![](../image/retropad/retro_a.png) | C | C | C | 2 | | 2 | | | ![](../image/retropad/retro_x.png) | Y | | Y | | | | | | ![](../image/retropad/retro_l1.png) | X | | X | | | | C | | ![](../image/retropad/retro_r1.png) | Z | | Z | | | | A | | ![](../image/retropad/retro_l2.png) | | | | | | | D | | ![](../image/retropad/retro_r2.png) | | | | | | | B | | ![](../image/retropad/retro_l3.png) | | | | | | | | | ![](../image/retropad/retro_r3.png) | | | | | | | | | ![](../image/retropad/retro_left_stick.png) X | | | | | Paddle | Trackball X | Thumb-stick X | | ![](../image/retropad/retro_left_stick.png) Y | | | | | | Trackball Y | Thumb-stick Y | | ![](../image/retropad/retro_right_stick.png) X | | | | | | | Slider Y | | ![](../image/retropad/retro_right_stick.png) Y | | | | | | | Slider X | ## Mouse | RetroMouse Inputs | [MD Mouse](https://segaretro.org/Sega_Mouse) | |-------------------------------------------------------|-----------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | MD Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | MD Mouse Left | | ![](../image/retromouse/retro_right.png) Mouse 2 | MD Mouse Right | | ![](../image/retromouse/retro_middle.png) Mouse 3 | MD Mouse Start | | Wheel Down | MD Mouse Center | ## Pointer | RetroPointer Inputs | [MS Graphic Board](https://segaretro.org/Sega_Graphic_Board) | |------------------------------------------------------------------------------------------------------------------------|-------------------------| | ![](../image/retromouse/retro_mouse.png) or ![](../image/Button_Pack/Gestures/Gesture_Finger_Front.png) Pointer Position | MS Graphic Board Stylus | | ![](../image/retromouse/retro_left.png) Mouse 1 | MS Graphic Board Pen | | ![](../image/retromouse/retro_right.png) Mouse 2 | MS Graphic Board Menu | | ![](../image/retromouse/retro_middle.png) Mouse 3 | MS Graphic Board Do | ## Lightgun | RetroLightgun Inputs | [MD Menacer](https://segaretro.org/Menacer) | [MD Justifier](https://segaretro.org/The_Justifier) | [MS Light Phaser](https://segaretro.org/Light_Phaser) | |--------------------------------------------------------|----------------------|------------------------|---------------------------| | ![](../image/retromouse/retro_mouse.png) Gun Crosshair | MD Menacer Crosshair | MD Justifier Crosshair | MS Light Phaser Crosshair | | Gun Trigger | MD Menacer A | MD Justifier A | MS Light Phaser A | | Gun Aux A | MD Menacer B | MD Justifer B | MS Light Phaser B | | Gun Aux B | MD Menacer C | MD Justifer C | MS Light Phaser C | | Gun Start | MD Menacer Start | MD Justifer Start | MS Light Phaser Start | ## Other | Inputs | [PICO tablet](https://segaretro.org/Sega_Pico) | [Terebi Oekaki tablet](https://segaretro.org/Terebi_Oekaki) | |--------------------------------------------------------------------------------------------------------------------------|---------------------------|---------------------------| | ![](../image/retromouse/retro_mouse.png) or ![](../image/Button_Pack/Gestures/Gesture_Finger_Front.png) Pointer Position | PICO tablet Stylus | Terebi Oekaki tablet Stylus | | ![](../image/retromouse/retro_left.png) Mouse 1 | PICO tablet Pen | Terebi Oekaki tablet Pen | | ![](../image/retromouse/retro_right.png) Mouse 2 | PICO tablet Red | | | ![](../image/retromouse/retro_middle.png) Mouse 3 | | Terebo Oekaki tablet Start | | Wheel Up | PICO tablet Previous page | | | Wheel Down | PICO tablet Next page | | | ![](../image/retropad/retro_dpad_up.png) | PICO tablet Up (White) | | | ![](../image/retropad/retro_dpad_down.png) | PICO tablet Down (Orange) | | | ![](../image/retropad/retro_dpad_left.png) | PICO tablet Left (Purple) | | | ![](../image/retropad/retro_dpad_right.png) | PICO tablet Right (Green) | | ## External Links - [Official Genesis Plus GX Github Repository](https://github.com/ekeeke/Genesis-Plus-GX) - [Libretro Genesis Plus GX Core Info File](https://github.com/libretro/libretro-super/blob/master/dist/info/genesis_plus_gx_libretro.info) - [Libretro Genesis Plus GX Github Repository](https://github.com/libretro/Genesis-Plus-GX) - [Report Libretro Genesis Plus GX Core Issues Here](https://github.com/libretro/Genesis-Plus-GX/issues) - [Gameplay Videos Playlist on YouTube](https://www.youtube.com/playlist?list=PLRbgg4gk_0If0UWkhjPbRmWUBcGaRiPZt) ## Sega 8/16-bit cores - [Sega - Master System (Emux SMS)](emux_sms.md) - [Sega - MS/MD/CD/32X (PicoDrive)](picodrive.md) - [Sega - MS/GG/SG-1000 (Gearsystem)](gearsystem.md) - [MSX/SVI/ColecoVision/SG-1000 (blueMSX)](bluemsx.md) ================================================ FILE: docs/library/geolith.md ================================================ # SNK - Neo Geo AES / MVS (Geolith) ## Background Geolith is a highly accurate Neo Geo AES/MVS emulator written in ISO C11. Geolith takes a different approach to Neo Geo emulation than most existing emulators, aiming for a home-console-first experience and using single file ROMs (which never need to be updated) similar to a typical home console emulator. Despite the focus on the home experience, Geolith also fully supports arcade mode. The Geolith core has been authored by - [Rupert Carmichael (carmiker)](https://github.com/carmiker) The Geolith core is licensed under - [BSD-3-Clause](https://github.com/libretro/geolith-libretro/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Geolith requires a BIOS. Required or optional firmware files go in the frontend's system directory. !!! attention Geolith requires BIOS files to function. Place the following files in RetroArch's system directory: | Filename | Description | md5sum | |:-----------------:|:----------------------------------:|:--------------------------------:| | aes.zip | Neo Geo AES BIOS - Required | ad9585c72130c56f04ae26aae87c289d | | neogeo.zip | Neo Geo MVS BIOS - Required | 00dad01abdbf8ea9e79ad2fe11bdb182 | ## Extensions Content that can be loaded by the Geolith core have the following file extensions: - .neo ## Features Frontend-level settings or features that the Geolith core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✔ | | LEDs | ✕ | ### Directories The Geolith core's library name is 'Geolith' The Geolith core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:----------------------:| | *.nv | NVRAM save | | *.mcr | Memory Card save | | *.srm | Cartridge battery save | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ### Geometry and timing - The Geolith core's core provided FPS is 59.599484 for AES and 59.185606 for MVS - The Geolith core's core provided sample rate is 55943.49Hz for AES and 55555Hz for MVS - The Geolith core provides adjustable overscan masking and aspect ratio options ## Core options The Geolith core has the following options that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **System Type (Restart)** [geolith_system_type] (**Neo Geo AES (Home Console)**|Neo Geo MVS (Arcade)|Universe BIOS (Community-enhanced BIOS)) Specify the System Type: AES, MVS, or Universe BIOS System - **Region (Restart)** [geolith_region] (**USA**|Japan|Asia|Europe) Specify the Region: USA, Japan, Asia, Europe - **Setting Mode (Restart, DIP Switch)** [geolith_settingmode] (**Off**|On) Bring up the System ROM menu at boot on arcade systems - **Four Player Mode (Restart, Asia/Japan MVS Only)** [geolith_4player] (**Off**|On) Set Four Player (dual MVS cabinet) mode for Asia/Japan MVS systems, for use with Kizuna Encounter or homebrew with four player support - **Freeplay (DIP Switch)** [geolith_freeplay] (**Off**|On) Play MVS games without the need to insert coins - **Mask Overscan (Top)** [geolith_overscan_t] (16|12|**8**|4|0) Mask off pixels hidden by a bezel or border on original CRTs (top) - **Mask Overscan (Bottom)** [geolith_overscan_b] (16|12|**8**|4|0) Mask off pixels hidden by a bezel or border on original CRTs (bottom) - **Mask Overscan (Left)** [geolith_overscan_l] (16|12|**8**|4|0) Mask off pixels hidden by a bezel or border on original CRTs (left) - **Mask Overscan (Right)** [geolith_overscan_r] (16|12|**8**|4|0) Mask off pixels hidden by a bezel or border on original CRTs (right) - **Palette** [geolith_palette] (**Resistor Network**|Raw) Set the Palette - **Aspect Ratio** [geolith_aspect] (**Perfectly Square Pixels (1:1 PAR)**|Ostensibly Accurate NTSC Aspect Ratio (45:44 PAR)|Very Traditional NTSC Aspect Ratio (4:3 DAR)) Set the Aspect Ratio - **Sprites-per-line limit (Hack)** [geolith_sprlimit] (**Hardware Accurate (96)**|Double (192)|Triple (288)|MAX 381 MEGA PRO-GEAR SPEC) Set the sprites-per-line limit - increasing causes glitches in some games - **Overclocking (Hack)** [geolith_oc] (**Off**|On) Annihilate your accuracy with The 24MHz Shock - expect glitches. DO NOT USE THIS FOR ALL GAMES, enable only for specific cases with major slowdown. ### Input Devices | Player 1/2/3/4 Joysticks | RetroPad Inputs | |-------------------------------------|------------------------------------------------| | Up | ![](../image/retropad/retro_dpad_up.png) | | Down | ![](../image/retropad/retro_dpad_down.png) | | Left | ![](../image/retropad/retro_dpad_left.png) | | Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_b.png) | | B | ![](../image/retropad/retro_a.png) | | C | ![](../image/retropad/retro_y.png) | | D | ![](../image/retropad/retro_x.png) | | Select/Coin | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | C+D | ![](../image/retropad/retro_l1.png) | | A+B | ![](../image/retropad/retro_r1.png) | | B+C | ![](../image/retropad/retro_l2.png) | | A+B+C | ![](../image/retropad/retro_r2.png) | | Test (Arcade, Player 1 Only) | ![](../image/retropad/retro_l3.png) | | Service (Arcade, Player 1 Only) | ![](../image/retropad/retro_r3.png) | | V-Liner | RetroPad Inputs | |-------------------------------------|------------------------------------------------| | Up | ![](../image/retropad/retro_dpad_up.png) | | Down | ![](../image/retropad/retro_dpad_down.png) | | Left | ![](../image/retropad/retro_dpad_left.png) | | Right | ![](../image/retropad/retro_dpad_right.png) | | Payout Table/Big | ![](../image/retropad/retro_b.png) | | Bet/Small | ![](../image/retropad/retro_a.png) | | Stop/Double-Up | ![](../image/retropad/retro_y.png) | | Start/Collect | ![](../image/retropad/retro_x.png) | | Operator Menu | ![](../image/retropad/retro_select.png) | | Clear Credit | ![](../image/retropad/retro_start.png) | | Coin 1 | ![](../image/retropad/retro_l1.png) | | Coin 2 | ![](../image/retropad/retro_r1.png) | | Hopper Out | ![](../image/retropad/retro_l2.png) | ## External Links - [Upstream Geolith Repository](https://gitlab.com/jgemu/geolith) - [Libretro Geolith Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/geolith_libretro.info) - [Libretro Geolith Repository](https://github.com/libretro/geolith-libretro) - [Report Geolith Core Issues Here](https://github.com/libretro/geolith-libretro/issues) ### See also - [Arcade (fbneo)](fbneo.md) ================================================ FILE: docs/library/gpsp.md ================================================ # Nintendo - Game Boy Advance (gpSP) ## Background gpSP is a Game Boy Advance emulator based on notaz' fork of gpSP with additional codebase improvements. ### Author/License The gpSP core has been authored by - Exophase The gpSP core is licensed under - [GPLv2](https://github.com/libretro/gpsp/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the gpSP core have the following file extensions: - .gba - .bin ## Databases RetroArch database(s) that are associated with the gpSP core: - [Nintendo - Game Boy Advance](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Game%20Boy%20Advance.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:-------------:|:---------------------------------:|:--------------------------------:| | gba_bios.bin | Game Boy Advance Image - Optional | a860e8c0b6d573d191e4ec7db1b1e4f6 | ## Features Frontend-level settings or features that the gpSP core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | [RetroArch SaveRAM Autosave Interval support](https://github.com/libretro/RetroArch/issues/16323#issuecomment-1977792161) | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✔ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The gpSP core's directory name is 'gpSP' The gpSP core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.srm (Cartridge battery save) **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The gpSP core's core provided FPS is 59.72750057 - The gpSP core's core provided sample rate is 65536 Hz - The gpSP core's core provided aspect ratio is 3/2 ## Controllers The gpSP core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. - **RetroPad** - Joypad - RetroPad w/Analog - Joypad - There's no reason to switch to this. ### Controller tables #### Joypad ![](../image/controller/gba.png) | User 1 Remap descriptors | RetroPad Inputs | |--------------------------|-------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | ## Compatibility | Game | Issue | |---------------------------------------|--------------------------------| | Banjo-Kazooie - Grunty's Revenge |Black screen during developer logo. | | Boktai Trilogy |The solar sensor is not emulated. | | Dragon Ball Z - The Legacy of Goku |Graphics glitches. | | Final Fantasy VI |Background/tiling order issues. | | Harry Potter - Quidditch World Cup |Crashes when going ingame. | | Koro Koro Puzzle Happy Panechu! |The tilt sensor is not emulated. | | Phantasy Star Collection |Phantasy Star 1 flickers - turn on Interframe Blending in core options to fix.| | Sims 2, The - Pets |Graphics glitches. Heavy flickering, black objects. | | Street Racing Syndicate |Crashes afer pressing Start.| | Super Street Fighter II Turbo/X Revival |Small graphics glitch. Selecting speed 'Turbo 1' and beyond on the character select screen makes the game speed window not fully visible. | | WarioWare: Twisted! |The tilt sensor is not emulated.| | Yoshi’s Universal Gravitation |The tilt sensor is not emulated.| ??? note "(1)" ![](../image/core/gpsp/goku.png) ??? note "(2)" ![](../image/core/gpsp/sims.png) ??? note "(3)" ![](../image/core/gpsp/fighter.png) ## External Links - [Official gpSP Website](http://notaz.gp2x.de/other.php) - [Official gpSP Github Repository](https://github.com/notaz/gpsp) - [Libretro gpSP Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/gpsp_libretro.info) - [Libretro gpSP Github Repository](https://github.com/libretro/gpsp) - [Report Libretro gpSP Core Issues Here](https://github.com/libretro/gpsp/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0Iczn5l7AfS11JNbXUv5Widl) ### See also #### Nintendo - Game Boy Advance - [Nintendo - Game Boy Advance (Beetle GBA)](beetle_gba.md) - [Nintendo - Game Boy Advance (Meteor)](meteor.md) - [Nintendo - Game Boy Advance (mGBA)](mgba.md) - [Nintendo - Game Boy Advance (TempGBA)](tempgba.md) - [Nintendo - Game Boy Advance (VBA-M)](vba_m.md) - [Nintendo - Game Boy Advance (VBA Next)](vba_next.md) ================================================ FILE: docs/library/gw.md ================================================ # Handheld Electronic (GW) ## Background A libretro core for Game & Watch simulators. It runs simulators converted from source code for the games available at [MADrigal](http://www.madrigaldesign.it/sim/). The converted games are available at [buildbot](https://buildbot.libretro.com/assets/cores/Handheld%20Electronic%20Game/). The GW core has been authored by - Andre Leiradella The GW core is licensed under - [zlib](https://github.com/libretro/gw-libretro/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the GW core have the following file extensions: - .mgw ## Databases RetroArch database(s) that are associated with the GW core: - [Handheld Electronic Game](https://github.com/libretro/libretro-database/blob/master/rdb/Handheld%20Electronic%20Game.rdb) ## Features Frontend-level settings or features that the GW core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✕ | | Screenshots | ✔ | | Saves | ✕ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The GW core's internal core name is 'Game & Watch' ### Geometry and timing - The GW core's core provided FPS is 60 - The GW core's core provided sample rate is 44100 Hz - The GW core's core provided aspect ratio is dependent on the loaded content. ## Controllers The GW core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 - 2 device types - None - Doesn't diable input. - **Controller** - Joypad - Stay on this. ### Controller tables #### Joypad !!! attention What the inputs do are game specific. Without having anything selected, you can use the Start input to see a Controller overlay to see what the game specific inputs are. ![](../image/core/gw/overlay.png) | User 1 Remap descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Y | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | Up | ![](../image/retropad/retro_dpad_up.png) | | Down | ![](../image/retropad/retro_dpad_down.png) | | Left | ![](../image/retropad/retro_dpad_left.png) | | Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | X | ![](../image/retropad/retro_x.png) | | L1 | ![](../image/retropad/retro_l1.png) | | R1 | ![](../image/retropad/retro_r1.png) | | L2 | ![](../image/retropad/retro_l2.png) | | R2 | ![](../image/retropad/retro_r2.png) | | L3 | ![](../image/retropad/retro_l3.png) | | R3 | ![](../image/retropad/retro_r3.png) | ## External Links - [MADrigal Website](http://www.madrigaldesign.it/sim/) - [Libretro GW Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/gw_libretro.info) - [Libretro GW Github Repository](https://github.com/libretro/gw-libretro) - [Report Libretro GW Core Issues Here](https://github.com/libretro/gw-libretro/issues) ================================================ FILE: docs/library/handy.md ================================================ # Atari - Lynx (Handy) ## Background Handy is an Atari Lynx video game system emulator that can be used as a libretro core. Handy was the original name of the Lynx project that was started at Epyx and then finished by Atari. ### Author/License The Handy core has been authored by - K. Wilkins The Handy core is licensed under - [zlib](https://sourceforge.net/projects/handy/) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Handy core have the following file extensions: - .lnx ## Databases RetroArch database(s) that are associated with the Handy core: - [Atari - Lynx](https://github.com/libretro/libretro-database/blob/master/rdb/Atari%20-%20Lynx.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:-------------:|:--------------------------:|:--------------------------------:| | lynxboot.img | Lynx Boot Image - Required | fcd403db69f54290b51035d82f835e7b | ## Features Frontend-level settings or features that the Handy core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✕ | | States | ✔ | | Rewind | ✔ | | Netplay (State based) | ✔ (not link-cable emulation) | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | Cheats (Cheats menu) | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Handy core's directory name is 'Handy' The Handy core saves/loads to/from these directories. **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The Handy core's core provided FPS is 75 - The Handy core's core provided sample rate is 22050 Hz - The Handy core's core provided aspect ratio is dependent on the ['Display rotation' core option](#core-options/). When set to None, the aspect ratio will be 80/51. When set to 90 or 240, the aspect ratio will be 51/80. ## Core options The Handy core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Display rotation** [handy_rot] (**None**/90/240) Self-explanatory. Need to restart content. ## Controllers The Handy core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. - **RetroPad** - Joypad - RetroPad w/Analog - Joypad - There's no reason to switch to this. ### Controller tables #### Joypad ![](../image/controller/lynx.png) | User 1 Remap descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Pause | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | Option 1 | ![](../image/retropad/retro_l1.png) | | Option 2 | ![](../image/retropad/retro_r1.png) | Supported combinations - Option 1 + Pause = Restarts game - Option 2 + Pause = Flips Screen ## Compatibility | Game | Issue | |--------------|-------------------------------------------------------------------------| | RoadBlasters | Graphics glitches. Minor flickering and glitches after starting a race. | ## External Links - [Official Handy Website](http://handy.sourceforge.net/) - [Official Handy Downloads](http://handy.sourceforge.net/download.htm) - [Libretro Handy Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/handy_libretro.info) - [Libretro Handy Github Repository](https://github.com/libretro/libretro-handy) - [Report Libretro Handy Core Issues Here](https://github.com/libretro/libretro-handy/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0IfDlFKLg0HMDXbn8BrcxbJV) ### See also #### Atari - Lynx - [Atari - Lynx (Beetle Lynx)](beetle_lynx.md) - [Atari - Lynx (Holani)](holani.md) ================================================ FILE: docs/library/hatari.md ================================================ # Atari - ST/STE/TT/Falcon (Hatari) ## Background Hatari is an Atari ST/STE/TT/Falcon system emulator that can be used as a libretro core. Hatari tries to emulate the hardware as close as possible so that it is able to run most of the old Atari games and demos. ### Author/License The Hatari core has been authored by - Nicolas Pomarède The Hatari core is licensed under - [GPLv2](https://github.com/libretro/hatari/blob/master/readme.txt) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Hatari core have the following file extensions: - .st - .msa - .zip - .stx - .dim - .ipf ## BIOS Required or optional firmware files go in the frontend's system directory. !!! attention The plain ST mode only works with TOS 1.00, 1.02, 1.04, or 2.06. STE mode requires any of the TOS versions 1.xx or 2.xx. TOS 3.0x is for TT, and TOS 4.0x is for Falcon. | Filename | Description | md5sum | |:--------:|:-------------------------:|:--------------------------------:| | tos.img | TOS Boot Image - Required | c1c57ce48e8ee4135885cee9e63a68a2 | ## Features Frontend-level settings or features that the Hatari core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✕ | | Screenshots | ✕ | | Saves | ✕ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Hatari core's internal core name is 'Hatari' The Hatari core saves/loads to/from these directories. **Frontend's System directory** - hatari.cfg (Hatari Config file) **User directory** - .hatari/ (Unused directory) ### Geometry and timing - The Hatari core's core provided FPS is (FPS) - The Hatari core's core provided sample rate is (Rate) - The Hatari core's core provided aspect ratio is (Ratio) ## Getting Started With Hatari !!! attention This guide was written by [AnicetusCer on the LibRetro Forums](https://forums.libretro.com/t/getting-started-with-hatari-atari-st-ste-tt-falcon-emulation/13237). This was written using Lakka 2.1 rc6 x86_64 I was excited to find out Lakka has an Atari ST core, but then disappointed that it chucked out some errors when I tried to “just load an .st image”. There really was not much of a guide out there, even to get started, So I picked apart a handful of posts and docs and wrote my own mini guide below. ### Quick Start - Get a copy of US TOS 1.02 , name and put it here; “/storage/system/tos.img” - Create a folder for your Atari ST games “/storage/roms/Atari - ST” - Create a hatari.cfg file in “/storage/system/hatari.cfg” with the following lines ``` [Floppy] bAutoInsertDiskB = TRUE FastFloppy = TRUE nWriteProtection = 0 szDiskAFileName = /storage/roms/Atari\ -\ ST/game.st szDiskBFileName = szDiskImageDirectory = /storage/roms/Atari\ -\ ST/ szDiskAZipPath = szDiskBZipPath = [ROM] szCartridgeImageFileName = szTosImageFileName = /storage/system/tos.img ``` - Changing Floppy disks can be achieved by accessing the Hatari menu and selecting the “Floppy” menu (see long winded explanation below) - So far I have found non of my own .st files get scanned into a playlist so I’ll have to build my own, but in the mean time to load a disk, in the Lakka menu go to “Load Content” > select you first game disk > then select to run it with the Hatari Core, it will now try to load the game without complaining it has no TOS. (ST games can have varying Hardware requirements, see “Long Winded Start” on how to change settings, but you should be able to play a lot of games with just the defaults. - Note on controllers, A controller can be used as both a mouse and joystick, see “Long Winded Start” for more info. ### Long Winded Start - The TOS image (TOS stands for THE Operating System, cool huh) Consider TOS like a bios image used for other consoles, it needs adding to the the “/storage/system” directory. The one the retroarch Hatari documents mention is the US TOS version 1.02 this was an Atari ST OS and is probably the most compatible version for playing games, if you want to learn more about the different TOS versions and which hardware systems they correspond to (ST, STE, TT & FALCON) here is a good link; [http://www.atarimania.com/atari-st-tt-falcon.html9](http://www.atarimania.com/atari-st-tt-falcon.html9). - I found Hatari would kick out this error when loading a game without the config set up “Can not load TOS file J’/usr/bin/TOS” This is because it was looking for the tos.img in the /usr/bin directory of Lakka, this is a read only location so we can not just drop the TOS image there, this is what the config file is needed for. This section tells Hatari to look for TOS in the location specified. ``` [ROM] szCartridgeImageFileName = szTosImageFileName = /storage/system/tos.img ``` - Hatari does not seem to have a default hatari.cfg in place when first loaded (Hence the error above), It expects it to be read from two places by default, /storage/.hatari/hatari.cfg and /storage/system/hatari.cfg, I prefer the latter as it is more visible, once you load your first game you can then access the Hatari menu and save over your first base config in either location with whatever settings you change. ### Controller and Hatari Menu (And Changing Floppy Disk) - The Hatari menu can be accessed using the default controller button “Y” when the core is loaded (IE during a game" (i was using a PlayStation 4 controller and it was the square button for me) - Once in the menu I found a real mouse is not usable, however you can press “select” on your controller to switch to mouse mode (there is also another button to display the mouse speed “ms” and another to change it), now you can navigate the menu. - The menu can be used to change your system settings, here you can; - Point to new TOS images - Change the CPU & the amount of memory (needed sometimes to get some games working, dropping to 512k can help with some earlier games) - Change floppy disks, “YOU WILL DO THIS A LOT WITH SOME GAMES” When the first game disk is loaded you can then access the Hatari menu, go to the “Floppy” Menu and then browse to a new disk to put into a drive (A or B). It is important that you choose not to reset the system when exiting the Hatari menu if still in a game (this is not selected by default , so you will be fine). - Add a HDD not really needed (for die hard Atari fans). - Change Keyboard and Joystick settings. - Change the screen size (Warning Hatari is strict when it comes to aspect ratios it will always want to use the available resolutions of 1990s Monitors, with a little tweaking you can get it to fill most of your modern screen) - Change the sound chip settings (don’t touch unless you know what you’re doing) - There is also a save state option in the memory menu (Save state is not available directly from Lakka for Hatari, but it is inside the emulator :slight_smile: ) - Once you have finished setting up your settings you can now save them using the save config button , rather than use the default location of /storage/.hatari/hatari.cfg I would navigate back to your initial basic config file /storage/hatari.cfg as it is more accessible and visible, Note if you like, you can have as many config files as you want, as long as you remember where you put them :blush: , "The Immortal (one of the hardest games ever made), for instance, needs its memory setting back to 512k with a 68000 cpu in st mode 1.02 TOS, so why not create an “immortal.cfg” with the right system settings and floppy already in the drive, then you can load it and it is all just done. ## Core options The Hatari core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Internal resolution** [Hatari_resolution] (**640x480**|832x576|832x588|800x600|960x720|1024x768|1024x1024) Set the internal resolution. ## Controllers The Hatari core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. There's no reason to switch to this. - **RetroPad** - Joypad - Stay on this. - RetroPad w/Analog - Joypad - Same as RetroPad. There's no reason to switch to this. ### Other controllers - Mouse - The Hatari core can emulate mouse inputs but this is done automatically and cannot be manually selected as a device type. ### Controller tables #### Joypad | User 1 Remap descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | Enter GUI | ![](../image/retropad/retro_y.png) | | Mouse mode toggle | ![](../image/retropad/retro_select.png) | | Keyboard overlay | ![](../image/retropad/retro_start.png) | | Up | ![](../image/retropad/retro_dpad_up.png) | | Down | ![](../image/retropad/retro_dpad_down.png) | | Left | ![](../image/retropad/retro_dpad_left.png) | | Right | ![](../image/retropad/retro_dpad_right.png) | | Fire | ![](../image/retropad/retro_a.png) | | Joystick number | ![](../image/retropad/retro_l1.png) | | Mouse speed | ![](../image/retropad/retro_r1.png) | | Toggle m/k status | ![](../image/retropad/retro_l2.png) | #### Keyboard | RetroKeyboard Inputs | Hatari core Inputs | |------------------------------|---------------------------| | Keyboard Backspace | - | | Keyboard Tab | - | | Keyboard Clear | - | | Keyboard Return | - | | Keyboard Pause | - | | Keyboard Escape | - | | Keyboard Space | - | | Keyboard Exclaim ! | - | | Keyboard Double Quote " | - | | Keyboard Hash # | - | | Keyboard Dollar $ | - | | Keyboard Ampersand & | - | | Keyboard Quote ' | - | | Keyboard Left Parenthesis ( | - | | Keyboard Right Parenthesis ) | - | | Keyboard Asterisk * | - | | Keyboard Plus + | - | | Keyboard Comma , | - | | Keyboard Minus - | - | | Keyboard Period . | - | | Keyboard Slash / | - | | Keyboard 0 | - | | Keyboard 1 | - | | Keyboard 2 | - | | Keyboard 3 | - | | Keyboard 4 | - | | Keyboard 5 | - | | Keyboard 6 | - | | Keyboard 7 | - | | Keyboard 8 | - | | Keyboard 9 | - | | Keyboard Colon : | - | | Keyboard Semicolon ; | - | | Keyboard Less than < | - | | Keyboard Equals = | - | | Keyboard Greater than > | - | | Keyboard Question ? | - | | Keyboard At @ | - | | Keyboard Left Bracket [ | - | | Keyboard Backslash \ | - | | Keyboard Right Bracket ] | - | | Keyboard Caret ^ | - | | Keyboard Underscore _ | - | | Keyboard Backquote ` | - | | Keyboard a | - | | Keyboard b | - | | Keyboard c | - | | Keyboard d | - | | Keyboard e | - | | Keyboard f | - | | Keyboard g | - | | Keyboard h | - | | Keyboard i | - | | Keyboard j | - | | Keyboard k | - | | Keyboard l | - | | Keyboard m | - | | Keyboard n | - | | Keyboard o | - | | Keyboard p | - | | Keyboard q | - | | Keyboard r | - | | Keyboard s | - | | Keyboard t | - | | Keyboard u | - | | Keyboard v | - | | Keyboard w | - | | Keyboard x | - | | Keyboard y | - | | Keyboard z | - | | Keyboard Delete | - | | Keyboard Keypad 0 | - | | Keyboard Keypad 1 | - | | Keyboard Keypad 2 | - | | Keyboard Keypad 3 | - | | Keyboard Keypad 4 | - | | Keyboard Keypad 5 | - | | Keyboard Keypad 6 | - | | Keyboard Keypad 7 | - | | Keyboard Keypad 8 | - | | Keyboard Keypad 9 | - | | Keyboard Keypad Period . | - | | Keyboard Keypad Divide / | - | | Keyboard Keypad Multiply * | - | | Keyboard Keypad Minus - | - | | Keyboard Keypad Plus + | - | | Keyboard Keypad Enter | - | | Keyboard Keypad Equals = | - | | Keyboard Up | - | | Keyboard Down | - | | Keyboard Right | - | | Keyboard Left | - | | Keyboard Insert | - | | Keyboard Home | - | | Keyboard End | - | | Keyboard Page Up | - | | Keyboard Page Down | - | | Keyboard F1 | - | | Keyboard F2 | - | | Keyboard F3 | - | | Keyboard F4 | - | | Keyboard F5 | - | | Keyboard F6 | - | | Keyboard F7 | - | | Keyboard F8 | - | | Keyboard F9 | - | | Keyboard F10 | - | | Keyboard F11 | - | | Keyboard F12 | - | | Keyboard F13 | - | | Keyboard F14 | - | | Keyboard F15 | - | | Keyboard Num Lock | - | | Keyboard Caps Lock | - | | Keyboard Scroll Lock | - | | Keyboard Right Shift | - | | Keyboard Left Shift | - | | Keyboard Right Control | - | | Keyboard Left Control | - | | Keyboard Right Alt | - | | Keyboard Left Alt | - | | Keyboard Right Meta | - | | Keyboard Left Meta | - | | Keyboard Right Super | - | | Keyboard Left Super | - | | Keyboard Mode | - | | Keyboard Compose | - | | Keyboard Help | - | | Keyboard Print | - | | Keyboard Sys Req | - | | Keyboard Break | - | | Keyboard Menu | - | | Keyboard Power | - | | Keyboard € | - | | Keyboard Undo | - | | Keyboard Unmapped | - | | Keyboard Unknown | - | #### Mouse | RetroMouse Inputs | Hatari core inputs | |-------------------------------------------------------|--------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | Mouse Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | Mouse Right Button | ## Compatibility - Hatari compatibility can be found [here](https://hg.tuxfamily.org/mercurialroot/hatari/hatari/raw-file/tip/doc/compatibility.html) ## External Links - [Official Hatari Website](http://hatari.tuxfamily.org/) - [Official Hatari Downloads](http://hatari.tuxfamily.org/download.html) - [Libretro Hatari Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/hatari_libretro.info) - [Libretro Hatari Github Repository](https://github.com/libretro/hatari) - [Report Libretro Hatari Core Issues Here](https://github.com/libretro/hatari/issues) ================================================ FILE: docs/library/higan_accuracy.md ================================================ # Nintendo - SNES / Famicom (higan Accuracy) ## Background A port of higan v106's Super Famicom emulation core to libretro. This core is the most in sync with upstream higan. - Most accurate SNES emulation available. - Simplified and easily accessible Super Game Boy functionality compared to the other bsnes cores. ### Author/License The higan Accuracy core has been authored by - byuu The higan Accuracy core is licensed under - [GPLv3](https://gitlab.com/higan/higan/blob/master/LICENSE.txt) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the higan Accuracy core have the following file extensions: - .sfc - .smc - .gb - .gbc - .bml - .rom ## Databases RetroArch database(s) that are associated with the higan Accuracy core: - [Nintendo - Super Nintendo Entertainment System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System%20Hacks.rdb) - [Nintendo - Super Nintendo Entertainment System Hacks](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System%20Hacks.rdb) - [Nintendo - Game Boy](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Game%20Boy.rdb) - [Nintendo - Game Boy Color](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Game%20Boy%20Color.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. !!! attention higan Accuracy uses split ROMS for special chip games. !!! attention Firmware files for SGB emulation need to be in directories called SGB1.sfc and SGB2.sfc in RetroArch's system directory. Look at the [Super GameBoy support section](#super-gameboy-support) for more information. Notable DSP1.mdDSP1B Games: - Super Mario Kart - Pilotwings Notable DSP2 Games: - Dungeon Master Notable DSP3 Games: - SD Gundam GX Notable DSP4 Games: - Top Gear 3000 Notable Cx4 Games: - Mega Man X2 - Mega Man X3 | Filename | Description | md5sum | |:----------------------:|:--------------------------------------:|:--------------------------------:| | dsp1.data.rom | DSP1 co-processor firmware - Optional | 3d81b45fa0c2aa8b852dfb1ece7c0971 | | dsp1.program.rom | DSP1 co-processor firmware - Optional | ae209fbe789fbf11a48aea5ab1197321 | | dsp1b.data.rom | DSP1B co-processor firmware - Optional | 1e3f568634a7d8284020dddc0ae905bc | | dsp1b.program.rom | DSP1B co-processor firmware - Optional | d10f446888e097cbf500f3f663cf4f6d | | dsp2.data.rom | DSP2 co-processor firmware - Optional | e9417e29223b139c3c4b635a2a3b8744 | | dsp2.program.rom | DSP2 co-processor firmware - Optional | aa6e5922a3ed5ded54f24247c11143c5 | | dsp3.data.rom | DSP3 co-processor firmware - Optional | 0a81210c0a940b997dd9843281008ee6 | | dsp3.program.rom | DSP3 co-processor firmware - Optional | d99ca4562818d49cee1f242705bba6f8 | | dsp4.data.rom | DSP4 co-processor firmware - Optional | ee4990879eb68e3cbca239c5bc20303d | | dsp4.program.rom | DSP4 co-processor firmware - Optional | a151023b948b90ffc23a5b594bb6fef2 | | cx4.data.rom | CX4 co-processor firmware - Optional | 037ac4296b6b6a5c47c440188d3c72e3 | | st010.data.rom | ST010 co-processor firmware - Optional | 254d70762b6f59f99c27c395aba7d07d | | st010.program.rom | ST010 co-processor firmware - Optional | 1d70019179a59a566a0bb5d3f2845544 | | st011.data.rom | ST011 co-processor firmware - Optional | 10bd3f4aa949737ab9836512c35bcc29 | | st011.program.rom | ST011 co-processor firmware - Optional | 95222ebf1c0c2990bcf25db43743f032 | | st018.data.rom | ST018 co-processor firmware - Optional | 49c898b60d0f15e90d0ba780dd12f366 | | st018.program.rom | ST018 co-processor firmware - Optional | dda40ccd57390c96e49d30a041f9a9e7 | | SGB1.sfc/sgb1.boot.rom | Super Game Boy BIOS - Optional | | | SGB1.sfc/program.rom | Super Game Boy ROM - Optional | | | SGB2.sfc/sgb2.boot.rom | Super Game Boy 2 BIOS - Optional | | | SGB2.sfc/program.rom | Super Game Boy 2 ROM - Optional | | ## Features Frontend-level settings or features that the higan Accuracy core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | - | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | - | | LEDs | ✕ | ### Directories The higan Accuracy core's internal core name is 'higan (Super Famicom Accuracy)' The higan Accuracy core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.srm (Cartridge battery save) **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The higan Accuracy core's core provided FPS is (FPS) - The higan Accuracy core's core provided sample rate is (Rate) - The higan Accuracy core's core provided aspect ratio is (Ratio) ## Super Gameboy Support The higan Accuracy core uses a simplified Super Game Boy routine that makes it much easier to access this feature than with the old v094-based cores. Instead of using the complex, CLI-based 'subsystem' launch commands, it looks for the necessary files in the system/BIOS directory whenever you feed the core a *.gb/c file. To get it working, you'll need one or more Super Game Boy ROMs and the sgb.boot.rom BIOS. **Step 1** Make 2 subdirectories in RetroArch's system directory, one named SGB1.sfc and the other named SGB2.sfc. **Step 2** Copy your original Super Game Boy ROM into the SGB1.sfc directory and then rename it to program.rom. Copy your Super Game Boy 2 ROM into the SGB2.sfc directory and then rename it program.rom, as well. **Step 3** Copy your sgb.boot.rom BIOS into each of your SGB1.sfc and SGB2.sfc directories, and rename them to sgb1.boot.rom and sgb2.boot.rom, respectively. The ['Preferred Super GameBoy BIOS' core option](#core-options) lets you choose which of the two SGB BIOSes to use. **Step 4** Load a SGB-supported GB.mdGBC rom. **Done** ![](../image/core/higan/sgb.png) !!! warning There may be graphical glitches when Rewind is set to On in RetroArch's settings. ## MSU-1 !!! attention MSU-1 support in this core is complex. **Use the [Snes9x core](../library/snes9x#msu-1-support) for simplified and easily accessible MSU-1 support.** MSU-1 support can be used by loading a correct .bml file. There's documentation for loading MSU-1 games in standalone higan [here](https://higan.readthedocs.io/en/stable/guides/import/#msu-1-games). ## Core options The higan Accuracy core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Internal resolution** [higan_sfc_internal_resolution] (**512x480**|512x448|512x240|512x224|256x240|256x224) Self-explanatory. ??? note "512x480" ![](../image/core/higan/512x480.png) ??? note "512x448" ![](../image/core/higan/512x448.png) ??? note "512x240" ![](../image/core/higan/512x240.png) ??? note "512x224" ![](../image/core/higan/512x224.png) ??? note "256x240" ![](../image/core/higan/256x240.png) ??? note "256x224" ![](../image/core/higan/256x224.png) - **Color emulation** [higan_sfc_color_emulation] (**OFF**|ON) Simulates the way a console’s display device differs from modern computer monitor’s colour reproduction. In particular, it simulates the slightly-different gamma correction used by the Super Famicom. ??? note "Color emulation - Disabled" ![](../image/core/higan/color_off.png) ??? note "Color emulation - Enabled" ![](../image/core/higan/color_on.png) - **Blur emulation** [higan_sfc_blur_emulation] (**OFF**|ON) Simulates the limited horizontal resolution of standard-definition TVs by blurring together horizontally-adjacent pixels. Games like Jurassic Park for the Super Famicom depend on this to emulate a transparency effect. ??? note "Blur emulation - Disabled" ![](../image/core/higan/blur_off.png) ??? note "Blur emulation - Enabled" ![](../image/core/higan/blur_on.png) - **Scanline emulation** [higan_sfc_scanline_emulation] (**OFF**|ON) Currently does not function properly. - **Preferred Super GameBoy BIOS (restart)** [higan_sfc_sgb_bios] (**SGB1.sfc/**|SGB2.sfc/) Choose what Super GameBoy BIOS you want to use. Look at the [Super GameBoy Support section](#super-gameboy-support) for more information. ## Controllers The higan Accuracy core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Input disabled. - [**SNES Joypad**](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller) - Joypad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse ### User 2 device types - None - Input disabled. - [**SNES Joypad**](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller) - Joypad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse - [Multitap](http://nintendo.wikia.com/wiki/Super_Multitap) - Joypad - Allows for up to five players to play together in multitap games. - [SuperScope](https://en.wikipedia.org/wiki/Super_Scope) - Lightgun - Inputs are not hooked up in this core. - [Justifier](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - Inputs are not hooked up in this core. - [Justifiers](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - Two Justifiers are plugged in, for two-player Justifier games. Inputs are not hooked up in this core. ### Multitap support Activating multitap support in compatible games can be configured by switching to the [Multitap device type](#controllers) for User 2. ### Controller tables #### Joypad ![](../image/controller/snes.png) | User 1 - 5 Remap descriptors | RetroPad Inputs | |------------------------------|-------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Y | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | X | ![](../image/retropad/retro_x.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | #### Mouse | RetroMouse Inputs | SNES Mouse | |-----------------------------------------------------|---------------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | SNES Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | SNES Mouse Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | SNES Mouse Right Button | ## Compatibility The higan Accuracy core fully emulates all SNES games that have ever been officially released. Incompatible with ROM hacks made to take advantage of emulator quirks, much like real hardware. ## External Links - [Official higan Website](https://byuu.org/) - [Official higan Upstream Downloads](https://byuu.org/emulation/higan/) - [Libretro higan Accuracy Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/higan_sfc_libretro.info) - [Libretro higan Accuracy Gitlab Repository](https://gitlab.com/higan/higan) - [Report Libretro higan Accuracy Core Issues Here](https://github.com/libretro/libretro-meta/issues) ### See also #### Nintendo - Game Boy (+ Color) - [Nintendo - Game Boy / Color (Emux GB)](emux_gb.md) - [Nintendo - Game Boy / Color (Gambatte)](gambatte.md) - [Nintendo - Game Boy / Color (Gearboy)](gearboy.md) - [Nintendo - Game Boy / Color (SameBoy)](sameboy.md) - [Nintendo - Game Boy / Color (TGB Dual)](tgb_dual.md) - [Nintendo - Game Boy Advance (mGBA)](mgba.md) - [Nintendo - Game Boy Advance (VBA-M)](vba_m.md) - [Nintendo - SNES / Famicom (nSide Balanced)](nside_balanced.md) - [Nintendo - SNES / Famicom (Mesen-S)](mesen-s.md) #### Nintendo - Super Nintendo Entertainment System (+ Hacks) - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (nSide Balanced)](nside_balanced.md) - [Nintendo - SNES / Famicom (Mesen-S)](mesen-s.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) ================================================ FILE: docs/library/holani.md ================================================ # Atari - Lynx (Holani) ## Background Holani is a cycle-stepped Atari Lynx video game system emulator that can be used as a libretro core. Holani's primary goal is to get closer to the Lynx hardware and provide a better emulation experience. ### Author/License The Holani core has been authored by - [LLeny](https://github.com/LLeny) The Holani core is licensed under - [GNU General Public License v3.0](https://github.com/LLeny/holani/blob/main/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Holani core have the following file extensions: - .lnx - .o ## Databases RetroArch database(s) that are associated with the Holani core: - [Atari - Lynx](https://github.com/libretro/libretro-database/blob/master/rdb/Atari%20-%20Lynx.rdb) ## BIOS Optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:-------------:|:--------------------------:|:--------------------------------:| | lynxboot.img | Lynx Boot Image - Required | fcd403db69f54290b51035d82f835e7b | ## Features Frontend-level settings or features that the Holani core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay (State based) | ✔ (not link-cable emulation) | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | Cheats (Cheats menu) | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Holani core's directory name is 'Holani' The Holani core saves/loads to/from these directories. **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The Holani core's core provided FPS is dynamic - The Holani core's core provided sample rate is 16,000 Hz ## Controllers The Holani core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. - **RetroPad** - Joypad - RetroPad w/Analog - Joypad - There's no reason to switch to this. ### Controller tables #### Joypad ![](../image/controller/lynx.png) | User 1 Remap descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Pause | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | Option 1 | ![](../image/retropad/retro_l1.png) | | Option 2 | ![](../image/retropad/retro_r1.png) | Supported combinations - Option 1 + Pause = Restarts game - Option 2 + Pause = Flips Screen ## External Links - [Official Holani Website](https://github.com/LLeny/holani-retro) - [Official Holani Downloads](https://github.com/LLeny/holani-retro/releases) - [Libretro Holani Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/holani_libretro.info) - [Libretro Holani Github Repository](https://github.com/LLeny/holani-retro) - [Report Libretro Holani Core Issues Here](https://github.com/LLeny/holani-retro/issues) ### See also #### Atari - Lynx - [Atari - Lynx (Beetle Lynx)](beetle_lynx.md) - [Atari - Lynx (Handy)](handy.md) ================================================ FILE: docs/library/imageviewer.md ================================================ # Imageviewer ## Background View images ### Author/License The Imageviewer core has been authored by - The RetroArch Team The Imageviewer core is licensed under - [MIT](https://github.com/libretro/RetroArch/blob/master/cores/libretro-imageviewer/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Imageviewer core have the following file extensions: - .jpg - .jpeg - .png - .bmp - .psd - .tga - .gif - .hdr - .pic - .ppm - .pgm ## Features Frontend-level settings or features that the Imageviewer core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✕ | | Screenshots | ✔ | | Saves | ✕ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✕ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Imageviewer core's internal core name is 'image display' ### Geometry and timing - The Imageviewer core's core provided FPS is 60 - The Imageviewer core's core provided sample rate is 44100 Hz - The Imageviewer core's core provided aspect ratio is dependent on the loaded content. ## Controllers The Imageviewer core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. There's no reason to switch to this. - **RetroPad** - Joypad - Stay on this. - RetroPad w/Analog - Joypad - There's no reason to switch to this. ### Controller tables #### Joypad | RetroPad Inputs | Imageviewer core inputs | |------------------------------------------------|------------------------------------------------------------| | ![](../image/retropad/retro_y.png) | Automatic slideshow - Go to the next image every 2 seconds | | ![](../image/retropad/retro_dpad_up.png) | Go forward 5 images | | ![](../image/retropad/retro_dpad_down.png) | Go backward 5 images | | ![](../image/retropad/retro_dpad_left.png) | Go backward 1 image | | ![](../image/retropad/retro_dpad_right.png) | Go forward 1 image | ## External Links - [Libretro Imageviewer Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/imageviewer_libretro.info) - [Libretro Imageviewer Github Repository](https://github.com/libretro/RetroArch/tree/master/cores/libretro-imageviewer) - [Report Libretro Imageviewer Core Issues Here](https://github.com/libretro/RetroArch/issues) ### See also #### Media - [FFmpeg](ffmpeg.md) - [Game Music Emu](game_music_emu.md) - [PocketCDG](pocketcdg.md) ================================================ FILE: docs/library/jaxe.md ================================================ # XO-CHIP/CHIP-8 (JAXE) *WIP* ## Background A fully-featured, cross platform XO-CHIP/S-CHIP/CHIP-8 emulator written in C. The JAXE core has been authored by - phcoder (Vladimir Serbinenko) - kurtjd (Kurtis Dinelle) The JAXE core is licensed under - [MIT](https://github.com/kurtjd/jaxe/blob/main/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Tecnical Info The original CHIP-8 virtual machine was designed with the following specs: - 35 opcodes - 4kb RAM - 16 8-bit general purpose registers - 16-bit program counter, stack pointer, and index registers - 8-bit delay and sound timer registers - 64x32 monochrome display - 16-key keypad (0-F) - Program memory starting at address 0x200 Due to the way CHIP-8 was designed, the "flicker" that happens when sprites are drawn is normal. Games developed for it also rarely made any attempt to cap their frame rate due to the slow hardware of the time hence the need to artificially slow the CPU down on modern emulators. In the early 90s, Andreas Gustafsson created a port for the HP48 calculator which was eventually superseded by S-CHIP 1.0/1.1 created by Erik Bryntse. The S-CHIP added several features as well as accidentally (or intentionally?) modifying the behavior of several original opcodes: - 9 new opcodes - 128x64 HI-RES display - Persistent storage - Modified Bnnn, Fx55, Fx65, Dxyn, 8xy6, and 8xyE instructions With time, it seems the S-CHIP became more popular and many programs were written to work with its various quirks. Thus, JAXE defaults to original S-CHIP design however many of its quirks can be toggled for improved compatibility using the flags in the Options section below. However, recently John Earnest designed the XO-CHIP extension allowing CHIP-8 programs to take advantage of modern hardware to an extent. This extension adds several more instructions and features including: - 7 new opcodes - 16-bit addressing for a total of ~64kb RAM - Second display buffer allowing for 4 colors instead of the typical 2 - Improved sound support - Modified Fx75 and Fx85 instructions to allow for 16 user flags instead of typical 8 - JAXE currently supports all of these extensions. It should also be noted that JAXE stores its fonts in memory starting at address 0x0000 followed immediately by large fonts and finally immediately by the stack. Therefore the stack pointer initially points to address 0x00F0. ## Extensions Content that can be loaded by the JAXE core have the following file extensions: - .ch8 - .sc8 - .xo8 ## Databases RetroArch database(s) that are associated with the JAXE core: - [CHIP-8](https://github.com/libretro/libretro-database/blob/master/rdb/) ## BIOS JAXE does not require BIOS (bootrom) files to work. ## Features | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✔ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | Softpatching | ✔ | | Disk Control | ✕ | | Username | ✕ | | Crop Overscan (in RetroArch's Video settings) | ✕ | ### Directories The JAXE core's directory name is 'JAXE' ### Core provided aspect ratio JAXE's core provided aspect ratio is 2/1. ## Core options The JAXE core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. **Ram init quirk** [] (**ON**|OFF) **8xy6/8xyE quirk** [] (**ON**|OFF) **Fx55/Fx65 quirk** [] (**ON**|OFF) **Bnnn quirk** [] (**ON**|OFF) **Big Sprite LORES quirk** [] (**ON**|OFF) **00FE/00FF quirk** [] (**ON**|OFF) **Sprite Wrapping** [] (**ON**|OFF) **Collision Enumeration** [] (**ON**|OFF) **Collision with Bottom of Screen** [] (**ON**|OFF) **CPU frequency** [] (**1000**|1500|2000|3000|5000|10000|800|750|600|500|400|300) **Theme** [] (**Default**|Black and white|Inverted black and white|Blood|Hacker|Space|Crazy Orange|Cyberpunk) ## Controllers ### Device types The JAXE core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): #### User 1 - 1 device types - None - Input disabled. - **RetroPad** - Joypad - RetroPad w/Analog - Joypad - **There is no reason to switch to this.** ### Controller tables #### Joypad and analog device type table | User 1 - 1 input descriptors | | RetroPad | |------------------------------|---------------------------------------------|--------------------| | 0 | ![](../image/retropad/retro_b.png) | B | | 2 | ![](../image/retropad/retro_y.png) | Y | | 1 | ![](../image/retropad/retro_start.png) | Start | | 5 | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | | 8 | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | | 7 | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | | 9 | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | | 6 | ![](../image/retropad/retro_a.png) | A | | C | ![](../image/retropad/retro_x.png) | X | | 5 | ![](../image/retropad/retro_l1.png) | L | | A | ![](../image/retropad/retro_r1.png) | R | | B | ![](../image/retropad/retro_l2.png) | L2 | | D | ![](../image/retropad/retro_r2.png) | R2 | | E | ![](../image/retropad/retro_left_stick.png) | L3 Button | | F | ![](../image/retropad/retro_right_stick.png) | R3 Button | | ## External Links - [Libretro JAXE Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/jaxe_libretro.info) - [Libretro JAXE Github Repository](https://github.com/libretro/) - [Report JAXE Core Issues Here](https://github.com/libretro/) ## CHIP-8 - [CHIP-8 (Emux)](emux_chip8.md) ================================================ FILE: docs/library/jollycv.md ================================================ # ColecoVision/CreatiVision/My Vision (JollyCV) ## Background JollyCV is a multi-emulator supporting ColecoVision (including Super Game Module), CreatiVision, and My Vision. JollyCV is fast, accurate, and highly portable. The JollyCV core has been authored by - [Rupert Carmichael (carmiker)](https://github.com/carmiker) The JollyCV core is licensed under - [BSD-3-Clause](https://github.com/libretro/jollycv/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Required or optional firmware files go in the frontend's system directory. !!! attention JollyCV requires a BIOS for ColecoVision or CreatiVision content. Place the following files in RetroArch's system directory. | Filename | Description | md5sum | |:-----------------:|:----------------------------------:|:--------------------------------:| | coleco.rom | ColecoVision BIOS - Required | 2c66f5911e5b42b8ebe113403548eee7 | | bioscv.rom | CreatiVision BIOS - Required | 3b1ef759d8e3fb4071582efd33dd05f9 | ## Extensions Content that can be loaded by the JollyCV core have the following file extensions: - .col - .rom - .myv - .bin RetroArch database(s) that are associated with the JollyCV core: - [Coleco - ColecoVision](https://github.com/libretro/libretro-database/blob/master/rdb/Coleco%20-%20ColecoVision.rdb) ## Features Frontend-level settings or features that the JollyCV core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | Softpatching | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✔ | | LEDs | ✕ | ### Directories The JollyCV core's library name is 'JollyCV' The JollyCV core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:----------------------:| | *.srm | Cartridge save | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ### Geometry and timing - The JollyCV core's core provided FPS is 60 for NTSC and 50 for PAL - The JollyCV core's core provided sample rate is 48000Hz - The JollyCV core provides adjustable overscan masking and aspect ratio options ## Core options The JollyCV core has the following options that can be tweaked from the core options menu. The default setting is bolded. - **TMS9918 Palette** [jollycv_tmspalette] (**TeaTime**|SYoung|GCDatasheet) Set the Palette - **Aspect Ratio** [jollycv_aspect] (**Region-based Pixel Aspect Ratio**|Perfectly Square Pixels (1:1 PAR)|Very Traditional NTSC Aspect Ratio (4:3 DAR)|Ostensibly Accurate PAL Aspect Ratio) Set the Aspect Ratio - **Mask Overscan (Top)** [jollycv_overscan_t] (16|14|12|10|8|6|4|2|**0**) Mask off pixels hidden by a bezel or border on original CRTs (top) - **Mask Overscan (Bottom)** [jollycv_overscan_b] (16|14|12|10|8|6|4|2|**0**) Mask off pixels hidden by a bezel or border on original CRTs (bottom) - **Mask Overscan (Left)** [jollycv_overscan_l] (8|**6**|4|2|0) Mask off pixels hidden by a bezel or border on original CRTs (left) - **Mask Overscan (Right)** [jollycv_overscan_r] (8|**6**|4|2|0) Mask off pixels hidden by a bezel or border on original CRTs (right) ### Input Devices | ColecoVision Paddle (Super Action) | RetroPad Inputs | |-------------------------------------|------------------------------------------------| | Up | ![](../image/retropad/retro_dpad_up.png) | | Down | ![](../image/retropad/retro_dpad_down.png) | | Left | ![](../image/retropad/retro_dpad_left.png) | | Right | ![](../image/retropad/retro_dpad_right.png) | | Yellow (Fire L) | ![](../image/retropad/retro_b.png) | | Orange (Fire R) | ![](../image/retropad/retro_a.png) | | Purple | ![](../image/retropad/retro_y.png) | | Blue | ![](../image/retropad/retro_x.png) | | 1 | ![](../image/retropad/retro_l2.png) ![](../image/retropad/retro_b.png) | | 2 | ![](../image/retropad/retro_l2.png) ![](../image/retropad/retro_a.png) | | 3 | ![](../image/retropad/retro_l2.png) ![](../image/retropad/retro_y.png) | | 4 | ![](../image/retropad/retro_l2.png) ![](../image/retropad/retro_x.png) | | 5 | ![](../image/retropad/retro_r2.png) ![](../image/retropad/retro_b.png) | | 6 | ![](../image/retropad/retro_r2.png) ![](../image/retropad/retro_a.png) | | 7 | ![](../image/retropad/retro_r2.png) ![](../image/retropad/retro_y.png) | | 8 | ![](../image/retropad/retro_r2.png) ![](../image/retropad/retro_x.png) | | 9 | ![](../image/retropad/retro_l2.png) ![](../image/retropad/retro_select.png) | | 0 | ![](../image/retropad/retro_r2.png) ![](../image/retropad/retro_select.png) | | * | ![](../image/retropad/retro_select.png) | | # | ![](../image/retropad/retro_start.png) | | Spinner- | ![](../image/retropad/retro_l1.png) | | Spinner+ | ![](../image/retropad/retro_r1.png) | | CreatiVision Paddle | RetroPad Inputs | |-------------------------------------|------------------------------------------------| | Up | ![](../image/retropad/retro_dpad_up.png) | | Down | ![](../image/retropad/retro_dpad_down.png) | | Left | ![](../image/retropad/retro_dpad_left.png) | | Right | ![](../image/retropad/retro_dpad_right.png) | | Fire L | ![](../image/retropad/retro_b.png) | | Fire R | ![](../image/retropad/retro_a.png) | | Start 1 | ![](../image/retropad/retro_select.png) | | Start 2 | ![](../image/retropad/retro_start.png) | | Reset | ![](../image/retropad/retro_l2.png) ![](../image/retropad/retro_select.png) | | Reset | ![](../image/retropad/retro_l2.png) ![](../image/retropad/retro_start.png) | | My Vision | RetroPad Inputs | |-------------------------------------|------------------------------------------------| | B (Up) | ![](../image/retropad/retro_dpad_up.png) | | C (Down) | ![](../image/retropad/retro_dpad_down.png) | | A (Left) | ![](../image/retropad/retro_dpad_left.png) | | D (Right) | ![](../image/retropad/retro_dpad_right.png) | | E | ![](../image/retropad/retro_select.png) | | 1 | ![](../image/retropad/retro_b.png) | | 2 | ![](../image/retropad/retro_a.png) | | 3 | ![](../image/retropad/retro_y.png) | | 4 | ![](../image/retropad/retro_x.png) | | 5 | ![](../image/retropad/retro_l2.png) ![](../image/retropad/retro_b.png) | | 6 | ![](../image/retropad/retro_l2.png) ![](../image/retropad/retro_a.png) | | 7 | ![](../image/retropad/retro_l2.png) ![](../image/retropad/retro_y.png) | | 8 | ![](../image/retropad/retro_l2.png) ![](../image/retropad/retro_x.png) | | 9 | ![](../image/retropad/retro_r2.png) ![](../image/retropad/retro_b.png) | | 10 | ![](../image/retropad/retro_r2.png) ![](../image/retropad/retro_a.png) | | 11 | ![](../image/retropad/retro_r2.png) ![](../image/retropad/retro_y.png) | | 12 | ![](../image/retropad/retro_r2.png) ![](../image/retropad/retro_x.png) | | 13 | ![](../image/retropad/retro_r1.png) | | 14 | ![](../image/retropad/retro_start.png) | ## External Links - [Upstream JollyCV Repository](https://gitlab.com/jgemu/jollycv) - [Libretro JollyCV Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/jollycv_libretro.info) - [Libretro JollyCV Repository](https://github.com/libretro/jollycv) - [Report JollyCV Core Issues Here](https://github.com/libretro/jollycv/issues) ### See also - [Coleco - ColecoVision (Gearcoleco)](gearcoleco.md) - [MSX/SVI/ColecoVision/SG-1000 (blueMSX)](bluemsx.md) ================================================ FILE: docs/library/jumpnbump.md ================================================ # Jump 'n Bump ## Background This is a game for the whole family. You play cute fluffy little bunnies and hop on each other's heads. At the beginning you are in the menu, where you have to let each active player jump over the tree trunk to enter the play area, and then walk to the right. You will then enter the arena. The aim is to jump on the other bunnies' heads… Jump 'n Bump was originally a DOS game by Brainchild Design, which was open sourced under the GPL license and ported to SDL, and then SDL2. ### Extra levels Additional levels are available on the website of [Brainchild Design](http://www.brainchilddesign.com/games/jumpnbump/levels/levels1.html). ### Author/License The Jump 'n Bump core has been authored by - loki666 The Jump 'n Bump core is licensed under - [GPLv2](https://github.com/fabiangreffrath/jumpnbump/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Jump 'n Bump core have the following file extensions: - .dat ## Databases RetroArch database(s) that are associated with the Jump 'n Bump core: - [Jump 'n Bump](https://github.com/libretro/libretro-database/blob/master/rdb/Jump%20'n%20Bump.rdb) ## BIOS There are no required BIOS. ## Features Frontend-level settings or features that the Jump 'n Bump core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✕ | | States | ✕ | | Rewind | ✕ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Jump 'n Bump core's internal core name is 'Jump 'n Bump' ### Geometry and timing - The Jump 'n Bump core's core provided FPS is (60) - The Jump 'n Bump core's core provided sample rate is 44100 Hz - The minivmac core's base width is 1200. - The minivmac core's base height is 768. - The minivmac core's core provided aspect ratio is 25/16. ## Core options The Jump 'n Bump core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Flip Level** [jnb-flip] (**OFF**|ON) ??? note "*Flip Level - Off*" ![](../image/core/jump_n_bump/jump-n-bump-flip-level-off.png) ??? note "*Flip Level - On*" ![](../image/core/jump_n_bump/jump-n-bump-flip-level-on.png) - **Flies** [jnb-flies] (**OFF**|ON) ??? note "*Flies - Off*" ![](../image/core/jump_n_bump/jump-n-bump-flies-off.png) ??? note "*Flies - On*" ![](../image/core/jump_n_bump/jump-n-bump-flies-on.png) ## Controllers The Jump 'n Bump core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 - 4 device types - None - Disables input. - **RetroPad** - Joypad - RetroPad with Analog ### Controller tables #### Joypad ![](../image/controller/nes.png) | User 1 - 4 Remap descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | ## External Links - [Jump 'n Bump Github Repository](https://github.com/fabiangreffrath/jumpnbump) - [Libretro Jump 'n Bump Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/jumpnbump_libretro.info) - [Libretro Jump 'n Bump Github Repository](https://github.com/libretro/jumpnbump-libretro) - [Report Libretro Jump 'n Bump Core Issues Here](https://github.com/libretro/jumpnbump-libretro/issues) ================================================ FILE: docs/library/kronos.md ================================================ # Sega - Saturn/ST-V (Kronos) ## Background Kronos is a fork of [Yabause](yabause.md). [It uses compute shaders](https://www.libretro.com/index.php/kronos-2-1-2-progress-report-sega-saturn-emulator/) and as such requires OpenGL 4.3. It emulates both the Sega Saturn and its arcade board version, the Sega Titan Video (ST-V). It's a fairly active project and the only Sega Saturn libretro core being officially supported by upstream. ### Author/License The Kronos core has been authored by - Guillaume Duhammel - Theo Berkau - Anders Montonen - devmiyax - François Caron The Kronos core is licensed under - [GPLv2](https://github.com/libretro/yabause/blob/kronos/yabause/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Kronos core have the following file extensions: - .cue - .iso - .ccd - .mds - .chd - .zip ## Databases RetroArch database(s) that are associated with the Kronos core: - [Sega - Saturn](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20Saturn.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:----------------------:|:--------------------------------------------------------------------------:|:--------------------------------:| | kronos/saturn_bios.bin | Saturn BIOS - Required for Saturn games | af5828fdff51384f99b3c4926be27762 | | kronos/stvbios.zip | ST-V BIOS - Required for ST-V games | | | mpr-18811-mx.ic1 | The King of Fighters '95 ROM Cartridge - Required for this game | 255113ba943c92a54facd25a10fd780c | | mpr-19367-mx.ic1 | Ultraman: Hikari no Kyojin Densetsu ROM Cartridge - Required for this game | 1cd19988d1d72a3e7caa0b73234c96b4 | This md5sum for the Saturn BIOS is just a hint, any valid saturn bios should work. Kronos will try searching for locations commonly used by other Sega Saturn libretro cores if it can't find a Sega Saturn bios at the expected path. Note that unlike yabause, Kronos won't automatically switch to HLE bios if a bios file is not present, because the Kronos project doesn't recommend using this HLE bios and actually won't provide support for any issue related to its usage. This is the reason for the file to be required. ## Features Frontend-level settings or features that the Kronos core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✔ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Savefiles Their location depends on the content running and the core options. By default they'll be stored in a `kronos` subdirectory of your savefiles directory, which will be split further between `saturn` and `stv` directories. However Kronos also has a core option named "Share saves with beetle", which will try to match Sega Saturn savefiles with Beetle-saturn. ### Geometry and timing - The Kronos core's core provided FPS is 60 for NTSC games and 50 for PAL games - The Kronos core's core provided sample rate is 44100 Hz - The Kronos core's core provided aspect ratio is 4/3 - The Kronos core will ask the frontend to rotate display for (ST-V) vertical games ## Loading Sega Saturn content - Kronos is not compatible with cue sheets containing references to audio files with wav/mp3/ogg/flac/ape extensions. - Zip files containing cue+bin files can be loaded directly, however the dump will be loaded in RAM (meaning it will use around 700MB of RAM depending on the size of the dump). - It is recommended to use [Redump](http://redump.org/) releases because this is the most thoroughly tested format. ## Core options The Kronos core has the following options that can be tweaked from the core options menu. The default settings are bolded. - **Force HLE BIOS** [kronos_force_hle_bios] (**disabled**|enabled) HLE BIOS will be forced. Use at your own risk, this is mainly for debugging purpose and is neither recommended nor supported. Requires a restart. - **Video format** [kronos_videoformattype] (**auto**|NTSC|PAL) Force video format to PAL or NTSC, default is auto which will try to detect from loaded content. - **Frameskip** [kronos_skipframe] (**0**|1|2|3|4|5) It will skip rendering at a fixed rate, it can improve playability dramatically on lower end devices - **SH-2 cache support (experimental)** [kronos_sh2coretype] (**kronos**|old) Support for SH-2's cache. It is required for some game to work properly. It can kill performance. - **Share saves with beetle** [kronos_use_beetle_saves] (**disabled**|enabled) Details above. Requires a restart. - **Addon Cartridge** [kronos_addon_cartridge] (**none** | 1M_extended_ram | 4M_extended_ram | 16M_extended_ram | 512K_backup_ram | 1M_backup_ram | 2M_backup_ram | 4M_backup_ram) This is the default cartridge you want Kronos to use. Note that your choice will be ignored if Kronos detects that the game requires a specific cartridge. Requires a restart. - **6Player Adaptor on Port 1** [kronos_multitap_port1] (**disabled**|enabled) Enable multitap in port 1. - **6Player Adaptor on Port 2** [kronos_multitap_port2] (**disabled**|enabled) Enable multitap in port 2. - **Resolution** [kronos_resolution_mode] (**original**|480p|720p|1080p|4k|8k) Modify rendering resolution. Requires a restart. - **Output to original resolution** [kronos_force_downsampling] (**disabled**|enabled) Useful when using resolution higher than your screen's, will also replace meshed transparency by real transparency to avoid moiré effect. - **Improved mesh** [kronos_meshmode] (**disabled**|enabled) Replace meshed transparency by real transparency. - **Improved banding** [kronos_bandingmode] (**disabled**|enabled) Apply gouraud shading instead of flat shading, requires OpenGL CS renderer. - **Wireframe mode** [kronos_wireframe_mode] (**disabled**|enabled) Wireframe mode, requires OpenGL CS renderer. - **ST-V Service/Test Buttons** [kronos_service_enabled] (**disabled**|enabled) Enable Service/Test for ST-V, to enter cabinet settings. By default they aren't mapped so that you won't press them by mistake. - **ST-V Favorite Region** [kronos_stv_favorite_region] (**EU**|US|JP|TW) Choose your favorite bios region for ST-V. It will be ignored if not compatible with your game. - **Bios Language** [kronos_language_id] (**English**|German|French|Spanish|Italian|Japanese) Choose your favorite language, will translate some games. Requires a restart. ## Controllers The Kronos core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User device types - None - **Saturn Pad** - Saturn 3D Pad - Saturn Wheel - Saturn Mouse ### Multitap support Must be enabled in core options. ### Controller tables #### Joypad ![](../image/controller/saturn.png) | User 1 - 12 Remap descriptors | RetroPad Inputs | |-------------------------------|----------------------------------------------| | A | ![](../image/retropad/retro_b.png) | | X | ![](../image/retropad/retro_y.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | B | ![](../image/retropad/retro_a.png) | | Y | ![](../image/retropad/retro_x.png) | | C | ![](../image/retropad/retro_l1.png) | | Z | ![](../image/retropad/retro_r1.png) | | L | ![](../image/retropad/retro_l2.png) | | R | ![](../image/retropad/retro_r2.png) | | Analog X | ![](../image/retropad/retro_left_stick.png) X | | Analog Y | ![](../image/retropad/retro_left_stick.png) Y | ## Compatibility - [Official Kronos Compatibility List](https://tradu-france.com/wiki-emu-compatibility/index.php?title=Compatibility_list_of_Kronos) ## Known issues - Savestates work but can sometime be quite unstable - Enabling both multitaps at the same time causes some kind of "autofire" bug - Switching between windowed and fullscreen will cause issues, you need to start the core in your prefered mode and stick with it - It seems there are compatibility issues between RetroArch's "threaded video" setting and this core. ## External Links - [Official Kronos Repository](https://github.com/FCare/Kronos) (please report issues there) - [Libretro Kronos Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/kronos_libretro.info) - [Libretro Kronos Github Repository](https://github.com/libretro/yabause/tree/kronos) - [Report Issues Here](https://github.com/libretro/yabause/issues) or [Here](https://github.com/FCare/Kronos/issues) ## Saturn - [Sega - Saturn (Beetle Saturn)](beetle_saturn.md) - [Sega - Saturn/ST-V (Kronos)](kronos.md) - [Sega - Saturn (Yabause)](yabause.md) - [Sega - Saturn (YabaSanshiro)](yabasanshiro.md) ================================================ FILE: docs/library/lowres_nx.md ================================================ # LowRes NX ## Background A port of the LowRes NX fantasy console to libretro. This core represents an imaginary handheld game console inspired by real 8- and 16-bit systems that is intended for simple games that can be programmed in second-generation, structured BASIC. It supports a d-pad, two action buttons and a keyboard for input. The LowRes NX platform comes with a variety of development tools including a Character Designer for editing sprites tile sand fonts, a Background Designer for tile maps and screen layouts and a Sound Composer for music and sound effects. The LowRes NX core has been authored by - Timoinutilis The LowRes NX core is licensed under - [zlib](https://github.com/timoinutilis/lowres-nx/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the LowRes NX core have the following file extensions: - .nx RetroArch database(s) that are associated with the LowRes NX core: - [LowRes NX](https://github.com/libretro/libretro-database/blob/master/rdb/LowRes%20NX.rdb) ## Features Frontend-level settings or features that the LowRes NX core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✕ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | - | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | - | | Disk Control | ✕ | | Username | - | | Language | - | | Crop Overscan | - | | LEDs | - | ## Geometry and timing - The LowRes NX core's core provided FPS is 60 - The LowRes NX core's core provided sample rate is 44100 Hz - The LowRes NX core's base width is 160 - The LowRes NX core's base height is 128 - The LowRes NX core's max width is 160 - The LowRes NX core's max height is 128 ## Controllers ### Device types The LowRes NX core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): #### User 1 - 1 device types - None - Doesn't disable input. - **RetroPad** - Joypad #### Joypad | RetroPad Inputs | User 1 input descriptors | |------------------------------------------------|--------------------------| | ![](../image/retropad/retro_b.png) | Button 2 | | ![](../image/retropad/retro_select.png) | Button SELECT | | ![](../image/retropad/retro_start.png) | Button START | | ![](../image/retropad/retro_dpad_up.png) | Button UP | | ![](../image/retropad/retro_dpad_down.png) | Button DOWN | | ![](../image/retropad/retro_dpad_left.png) | Button LEFT | | ![](../image/retropad/retro_dpad_right.png) | Button RIGHT | | ![](../image/retropad/retro_a.png) | BUTTON 1 | ## External Links - [Official LowRes NX Website](https://lowresnx.inutilis.com) - [Official LowRes NX Repository](https://github.com/timoinutilis/lowres-nx) - [Lowres Nx games](https://lowresnx.inutilis.com/programs.php) - [Libretro LowRes NX Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/lowresnx_libretro.info) - [Report Libretro LowRes NX Core Issues Here](https://github.com/timoinutilis/lowres-nx/issues) ================================================ FILE: docs/library/lrps2.md ================================================ # Sony - PlayStation (LRPS2) LRPS2 is a heavily modified hard fork of the excellent and mature PCSX2 emulator ported to libretro. It runs on Windows, macOS and Linux on the x86_64 architecture. MacOS computers running on Apple's ARM chipsets can still run it through the Rosetta x86 compatibility mode. This core does not work natively on ARM hardware, so it is not available on iOS/tvOS, Android, ARM Linux or Windows on ARM. It supports hardware rendering via OpenGL (Windows and Linux), Vulkan (natively on Windows and Linux and via MoltenVk on macOS) and D3D11/12 (Windows-only), as well as software rendering for games that require its additional accuracy. Note: the D3D11 renderer produces a black screen with working audio on some GPUs (toggling fast-forward should show a flickering picture), so if you encounter this, switch to another renderer, if possible. LRPS2 also includes a brand new, high-accuracy Vulkan compute renderer known as ParaLLEl-GS (from the same author and tech behind the ParaLLEl-RDP renderer now used by almost every major N64 emulator). The ParaLLEl-GS renderer is essentially a software renderer that relies on the parallel-processing power of a modern gaming GPU to accurately reproduce console behavior at or beyond full speed. As a result, this renderer is recommended, if your hardware is able to run it at full speed (should be fine on any discrete GPU and possibly on AMD integrated graphics; Intel integrated graphics do not appear to be fast enough at the time of this writing). LRPS2 core has been authored by - [Libretro]() - based on the PCSX2 emulator by the PCSX2 Dev Team LRPS2 core is licensed under - [GPLv3](https://github.com/libretro/ps2/blob/libretroization/COPYING.GPLv3) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Requirements CPU - Supports SSE2/AVX2 - PassMark Single Thread Performance rating near or greater than 1600/2100 - Two physical cores, with hyperthreading - Four physical cores, with or without hyperthreading GPU - Direct3D10/11 support - OpenGL 3.x/4.5 support - Vulkan 1.3+ support - PassMark G3D Mark rating around 3000 (GeForce GTX 750) - 2 GB/4 GB Video Memory RAM - 4GB/8GB !!! Attention Because of the complex nature of emulation, even if you meet the recommended requirements there will be games that will NOT run at full speed due to emulation imperfection, floating point emulation differences, issues with emulator itself or other problems. ## Setup (Required!!) For the LRPS2 core to function, it requires a set of real BIOS images dumped from your Playstation 2 console in accordance with your local laws, along with the `GameIndex.yaml` compatibility database. ### GameIndex.yaml In the past, most PS2 games required setting various hacks/options on a per-game basis to avoid compatibility issues and bugs. More recently, the PCSX2 team has automated this process by including a database of these per-game hacks/options in a file named `GameIndex.yaml`. Having this database in the correct spot is necessary for a good emulation experience. #### Core System Files Downloader The easiest way to get this file and put it where it needs to go is to stop by RetroArch's `Online Updater` and head to the `Core System Files Downloader`. Inside, you'll see a series of entries named for various cores. Look for `LRPS2.zip` and select it. The `Core System Files Downloader` will then download the `GameIndex.yaml` database and place it within the necessary directory structure automatically. #### Manually If you don't have access to the `Core System Files Downloader` for whatever reason (e.g., using the Steam release of RetroArch, or some other libretro frontend), you can still get everything you need manually. First, you will need to download the `GameIndex.yaml` file from the core's source code repository on [Github](https://github.com/libretro/ps2). [This](https://raw.githubusercontent.com/libretro/ps2/refs/heads/libretroization/bin/resources/GameIndex.yaml) is a direct link to the file, but if that link breaks in the future, the database file is typically housed in the `bin/resources` directory. Once you have the `GameIndex.yaml` database: 1. Navigate to your 'system'/BIOS directory (the location of which you can find/confirm by going to settings > directory in the RetroArch menu), then create a directory named `pcsx2` (must be in all lower-case). 2. Inside your new `pcsx2` directory, you'll make another directory named `resources` (again, all lower-case) 3. Place the `GameIndex.yaml` inside of it. The final structure should be `system/pcsx2/resources/GameIndex.yaml`. ### BIOS !!! Attention For compatibility reasons, it is recommended to not use a SCPH-10000 BIOS. !!! Notes - No specific filename required, as long as the BIOS was properly dumped the core will be able to find it. - The BIOS files must be extracted, the core will not be able to find them if they're zipped. - LRPS2 does not implement region locking, so if you have a PAL BIOS you can play NTSC games, and vice versa. However, this only applies with the `Fast Boot` core option enabled. LRPS2 requires a BIOS to work, the BIOS can be provided as a single 4MB .bin file or with additional files (usually .erom, .nvm, .rom1 and .rom2). In case you're having additional files with the .bin, make sure they're sharing the same filename or they'll be ignored. So as an example let's say you have a `SCPH-70004_BIOS_V12_EUR_200.BIN` file with an EROM file, a ROM1 file and a ROM2 file, it should look like this: ``` SCPH-70004_BIOS_V12_EUR_200.BIN SCPH-70004_BIOS_V12_EUR_200.EROM SCPH-70004_BIOS_V12_EUR_200.ROM1 SCPH-70004_BIOS_V12_EUR_200.ROM2 ``` #### How to set up your BIOS: 1. Go inside your RetroArch "system" folder (usually `retroarch/system/`, but if you're not sure check the path in `Settings > Directory > System/BIOS`). 2. Create a `pcsx2` folder (if you used the Core System Files Downloader to download the `GameIndex.yaml`, this folder structure should already exist). 3. Go inside the `pcsx2` folder and create a `bios` folder. 4. Go inside the `bios` folder and paste your BIOS file(s) here. For example, the default path would look like this: `system\pcsx2\bios\[bios_file_name].bin` If you're on a case-sensitive OS, make sure both `pcsx2` and `bios` folders are lowercase. ## Other required files and directories The file structure should look like this: ``` retroarch/ └── system/ └── pcsx2/ ├── bios/ ├── cheats/ ├── cheats_ws/ └── memcards/ (optional) ``` * `bios/` is where the BIOS files are located (see the ['BIOS'](#bios) section above), this should be created by the user. * `cheats/` is where you can store cheat patches, the folder is created on the first boot automatically. * `cheats_ws/` is where you can store additional widescreen patches, the folder is created on the first boot automatically. * `memcards/` is where the "legacy" memory cards are stored. This folder is optional, see the ['Directories'](#directories) section below. !!! Info Although the `cheats_ws` folder is empty when created, a very large number of widescreen patches are already included in the core itself. ## Extensions Content that can be loaded by the LRPS2 core have the following file extensions: - .elf - .iso - .ciso - .chd - .cso - .bin - .mdf - .nrg - .dump - .gz - .img - .m3u RetroArch database(s) that are associated with the LRPS2 core: - [Sony - PlayStation 2](https://github.com/libretro/libretro-database/blob/master/rdb/Sony%20-%20PlayStation%202.rdb) ## Features Frontend-level settings or features that the LRPS2 core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✕ | | Native Cheats | ✔ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✔ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✔ | | Username | ✕ | | Language | ✕ | | Crop Overscan[^2] | ✕ | | LEDs | ✕ | ## Directories LRPS2's library name is 'pcsx2' LRPS2 core saves/loads to/from these directories. **Frontend's System directory** - Legacy memory cards `retroarch/system/pcsx2/memcards/` ## Rumble support Rumble only works in the LRPS2 core when - The content being run has rumble support. - The frontend being used has rumble support. - The joypad device being used has rumble support. - The corresponding user's device type is set to **DualShock 2** ## Joypad ![](../image/controller/psx.png) | User 1 - 8 input descriptors | RetroPad Inputs | PlayStation Controller Inputs | DualShock Inputs | Analog Controller Inputs | Analog Joystick Inputs | neGcon Inputs | |-------------------------------|----------------------------------------------|------------------------------------------------|-------------------------------------------------|-------------------------------------------------|------------------------------------------------|---------------------------------| | Cross | ![](../image/retropad/retro_b.png) | ![](../image/Button_Pack/PS3/PS3_Cross.png) | ![](../image/Button_Pack/PS3/PS3_Cross.png) | ![](../image/Button_Pack/PS3/PS3_Cross.png) | ![](../image/Button_Pack/PS3/PS3_Cross.png) | Analog button I | | Square | ![](../image/retropad/retro_y.png) | ![](../image/Button_Pack/PS3/PS3_Square.png) | ![](../image/Button_Pack/PS3/PS3_Square.png) | ![](../image/Button_Pack/PS3/PS3_Square.png) | ![](../image/Button_Pack/PS3/PS3_Square.png) | Analog button II | | Select | ![](../image/retropad/retro_select.png) | ![](../image/Button_Pack/PS3/PS3_Select.png) | ![](../image/Button_Pack/PS3/PS3_Select.png) | ![](../image/Button_Pack/PS3/PS3_Select.png) | ![](../image/Button_Pack/PS3/PS3_Select.png) | | | Start | ![](../image/retropad/retro_start.png) | ![](../image/Button_Pack/PS3/PS3_Start.png) | ![](../image/Button_Pack/PS3/PS3_Start.png) | ![](../image/Button_Pack/PS3/PS3_Start.png) | ![](../image/Button_Pack/PS3/PS3_Start.png) | Start | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Up.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Up.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Up.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Up.png) | D-Pad Up | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Down.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Down.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Down.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Down.png) | D-Pad Down | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Left.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Left.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Left.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Left.png) | D-Pad Left | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Right.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Right.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Right.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Right.png) | D-Pad Right | | Circle | ![](../image/retropad/retro_a.png) | ![](../image/Button_Pack/PS3/PS3_Circle.png) | ![](../image/Button_Pack/PS3/PS3_Circle.png) | ![](../image/Button_Pack/PS3/PS3_Circle.png) | ![](../image/Button_Pack/PS3/PS3_Circle.png) | A | | Triangle | ![](../image/retropad/retro_x.png) | ![](../image/Button_Pack/PS3/PS3_Triangle.png) | ![](../image/Button_Pack/PS3/PS3_Triangle.png) | ![](../image/Button_Pack/PS3/PS3_Triangle.png) | ![](../image/Button_Pack/PS3/PS3_Triangle.png) | B | | L1 | ![](../image/retropad/retro_l1.png) | ![](../image/Button_Pack/PS3/PS3_L1.png) | ![](../image/Button_Pack/PS3/PS3_L1.png) | ![](../image/Button_Pack/PS3/PS3_L1.png) | ![](../image/Button_Pack/PS3/PS3_L1.png) | Left shoulder button (analog) | | R1 | ![](../image/retropad/retro_r1.png) | ![](../image/Button_Pack/PS3/PS3_R1.png) | ![](../image/Button_Pack/PS3/PS3_R1.png) | ![](../image/Button_Pack/PS3/PS3_R1.png) | ![](../image/Button_Pack/PS3/PS3_R1.png) | Right shoulder button (digital) | | L2 | ![](../image/retropad/retro_l2.png) | ![](../image/Button_Pack/PS3/PS3_L2.png) | ![](../image/Button_Pack/PS3/PS3_L2.png) | ![](../image/Button_Pack/PS3/PS3_L2.png) | ![](../image/Button_Pack/PS3/PS3_L2.png) | Analog button II | | R2 | ![](../image/retropad/retro_r2.png) | ![](../image/Button_Pack/PS3/PS3_R2.png) | ![](../image/Button_Pack/PS3/PS3_R2.png) | ![](../image/Button_Pack/PS3/PS3_R2.png) | ![](../image/Button_Pack/PS3/PS3_R2.png) | Analog button I | | L3 | ![](../image/retropad/retro_l3.png) | | ![](../image/Button_Pack/PS3/PS3_L3.png) | | | | | R3 | ![](../image/retropad/retro_r3.png) | | ![](../image/Button_Pack/PS3/PS3_R3.png) | | | | | Left Analog X | ![](../image/retropad/retro_left_stick.png) X | | ![](../image/Button_Pack/PS3/PS3_Left_Stick.png) | ![](../image/Button_Pack/PS3/PS3_Left_Stick.png) | Left Joystick X | Twist | | Left Analog Y | ![](../image/retropad/retro_left_stick.png) Y | | ![](../image/Button_Pack/PS3/PS3_Left_Stick.png) | ![](../image/Button_Pack/PS3/PS3_Left_Stick.png) | Left Joystick Y | | | Right Analog X | ![](../image/retropad/retro_right_stick.png) X | | ![](../image/Button_Pack/PS3/PS3_Right_Stick.png) | ![](../image/Button_Pack/PS3/PS3_Right_Stick.png) | Right Joystick X | | | Right Analog Y | ![](../image/retropad/retro_right_stick.png) Y | | ![](../image/Button_Pack/PS3/PS3_Right_Stick.png) | ![](../image/Button_Pack/PS3/PS3_Right_Stick.png) | Right Joystick Y | | ## Compatibility The current standalone development version is reported to be compatible with approximately 97.4% of 2,641 tested games as of August 2020. Compatibility means only that the game will not crash, lock up, or enter a loop; there can still be bugs, missing post-processing effects, textures, and shadows in many compatible games. This is especially the case in hardware mode; a slower software mode is available for bugs without workarounds. You can check compatibilirt list in [here](https://pcsx2.net/compatibility-list.html) ## External Links - [LRPS2 Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/pcsx2_libretro.info) - [LRPS2 Github Repository](https://github.com/libretro/ps2) - [Report LRPS2 Core Issues Here](https://github.com/libretro/ps2/issues) ## Libretro PS2 cores - [PlayStation 2 (Play!)](play.md) [^2]: Overscan cropping available via Core Options instead of frontend settings ================================================ FILE: docs/library/lutro.md ================================================ # Lua Engine (Lutro) ## Background Lutro is an experimental lua game framework that follows the [LÖVE API](https://love2d.org/wiki/Main_Page). Lutro games can be played with LibRetro/RetroArch through the Lutro core. #### How to start the Lutro core: - As an example showcasing loading content with the Lutro core, we will load the Pong game hosted on RetroArch's Content Downloader. You can do this by going to RetroArch's main menu screen and selecting 'Online Updater'. From there, select 'Content Downloader'.
![](../image/core/all/download.png)
- Select 'Lutro', then select 'Pong.lutro'. This should download and extract this file to RetroArch's Downloads directory.
![](../image/core/lutro/lutro.png)
- Go back to RetroArch's main menu screen. Select 'Load Content', then 'Downloads'.
![](../image/core/all/load.png)
![](../image/core/all/downloads.png)
- Select 'Pong.lutro'. - If you are asked which core to select, choose 'Lua Engine (Lutro)'. The content should now start running! ### Author/License The Lutro core has been authored by - Higor Euripedes - Jean-Andre Santoni The Lutro core is licensed under - [MIT](https://github.com/libretro/libretro-lutro/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Lutro core have the following file extensions: - .lutro - .lua ## Databases RetroArch database(s) that are associated with the Lutro core: - [Lutro](https://github.com/libretro/libretro-database/blob/master/rdb/Lutro.rdb) ## Features Frontend-level settings or features that the Lutro core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✕ | | Screenshots | ✕ | | Saves | ✕ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Lutro core's internal core name is 'lutro' ### Geometry and timing - The Lutro core's core provided FPS is 60 - The Lutro core's core provided sample rate is 44100 Hz - The LUtro core's core provided aspect ratio is (Ratio) ## Controllers The Lutro core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. There's no reason to switch to this. - **RetroPad** - Joypad - Stay on this. - RetroPad w/Analog - Joypad - Same as RetroPad. There's no reason to switch to this. ### Controller tables #### Joypad !!! attention What the inputs do are game specific. | User 1 Remap descriptors | RetroPad Inputs | Lutro core inputs | |--------------------------|------------------------------------------------|-------------------| | | ![](../image/retropad/retro_b.png) | B | | | ![](../image/retropad/retro_y.png) | Y | | | ![](../image/retropad/retro_select.png) | Select | | | ![](../image/retropad/retro_start.png) | Start | | Up | ![](../image/retropad/retro_dpad_up.png) | Up | | Down | ![](../image/retropad/retro_dpad_down.png) | Down | | Left | ![](../image/retropad/retro_dpad_left.png) | Left | | Right | ![](../image/retropad/retro_dpad_right.png) | Right | | | ![](../image/retropad/retro_a.png) | A | | | ![](../image/retropad/retro_x.png) | X | | | ![](../image/retropad/retro_l1.png) | L1 | | | ![](../image/retropad/retro_r1.png) | R1 | | | ![](../image/retropad/retro_l2.png) | L2 | | | ![](../image/retropad/retro_r2.png) | R2 | | | ![](../image/retropad/retro_l3.png) | L3 | | | ![](../image/retropad/retro_r3.png) | R3 | ## External Links - [Lua Website](https://www.lua.org/) - [LÖVE API Website](https://love2d.org/) - [Libretro Lutro Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/lutro_libretro.info) - [Libretro Lutro Github Repository](https://github.com/libretro/libretro-lutro) - [LUTRO LÖVE API Comparison](https://github.com/libretro/lutro-status) - [Lutro Github Wiki](https://github.com/libretro/libretro-lutro/wiki) - [Report Libretro Lutro Core Issues Here](https://github.com/libretro/libretro-lutro/issues) ### See also #### Custom Engine - [ChaiLove](chailove.md) ================================================ FILE: docs/library/m2000.md ================================================ # Philips - P2000T (M2000) ![](../image/core/m2000/machine.png) ## Background The P2000T was Philips' first computer for the home market in the early '80s, before they later switched to manufacturing MSX computers. The P2000T was a Z80-powered home computer, running at a clock speed of 2.5 MHz and it used a Mullard SAA5050 teletext display chip to produce the video picture. The machine was built like a tank and featured an integrated keyboard, power supply, two cartridge slots and a very innovative and fast Mini-Cassette system (MDCR), which was fully automated and used mini tapes that could hold up to 42 kilobytes of data. The P2000T was reasonably popular among hobbyists and kids in elementary schools in The Netherlands, as Philips promoted the machine strongly in the science and education sectors. Because of the relatively high introductory price and the fact that its SAA5050 video chip only supported a 40 x 24 character teletext display mode, the P2000T never became the success that Philips hoped for. While the system's video and sound capabilities were rather limited, some developers still were able to create remarkably good games, like a Pac-Man clone named "Ghosthunt", a Phoenix clone named "Fraxxon", a Lady Bug clone named "Lazy Bug" and a Breakout clone named "Brick-Wall". The P2000T (M2000) emulator core has been authored by: - Dion Olsthoorn - Marcel the Kogel (who wrote the original emulator back in 1997) and is licensed under: - [GPL3](https://github.com/p2000t/M2000/blob/main/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the M2000 core have the following file extensions: - .cas ## Features Frontend-level settings or features that the M2000 core respects: | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Directories The M2000 core's library name is 'M2000'. **Frontend's Save directory** | File | Description | |-------------|------------------------| | Default.cas | Writable cassette file, which is only created/attached when starting the M2000 core **without content** | ## Geometry and timing - The M2000 core's provided FPS is `50` - The M2000 core's provided sample rate is `30000` - The M2000 core's base width is `480` - The M2000 core's base height is `480` - The M2000 core's max width is `480` - The M2000 core's max height is `480` - The M2000 core's provided aspect ratio is `4/3` ## Usage You can use the M2000 core for playing P2000T cassette games, but you can also use it for programming your own P2000T Basic programs. ### Programming in Basic When you start the M2000 core **without content**, you will see the "Philips Cassette Basic" screen with the white cursor waiting for your input. Here you can type in your Basic program and load or save your programs. An - initially empty - cassette named `Default.cas` will be attached and stored in the M2000 Save directory. You can save a program using: ``` csave "program name" ``` ... and load it again using: ``` cload "program name" ``` Note that only the first(!) character of each program is used for identification, so e.g. a program named "hello world" can be loaded using `cload "h"`. To show the index of the cassette, press F3 or Shift + Numeric keypad 1. #### Game Focus mode Programming P2000T Basic using the M2000 core requires full keyboard access. This works best when the core is in **'Game Focus'** mode, which allows the M2000 core to take precedence in inputs. The easiest way to automatically enable 'Game Focus' mode for the M2000 core is in **Settings > Input** where you set the option called **Auto Enable 'Game Focus' Mode** to `Detect`. Or correspondingly in retroarch.cfg set `input_auto_game_focus = "2"`. Be aware that the default hotkey for toggling the **Game Focus** mode is the **Scroll Lock** key, which might not be present on your keyboard. If that's the case, you'll need to remap this hotkey to a more suitable key. ### Playing games The P2000T didn't came with any joystick ports, so every P2000T game relies on keyboard input. Usually the Space key is used to fire and the Arrow-keys to navigate, but other keys are also used to answer simple Yes/No questions or for entering the number of players. While the P2000T didn't have any joystick ports, there was a third-party company back in the '80s who was selling I/O cartridges to which you could connect up to 2 joysticks. These cartridges basically simulated actual key presses and that is exactly what the Joypad is doing in the M2000 core. Playing P2000T games using the M2000 core usually works best in one of these three ways: 1. Using **Keyboard only** This basically means that you play the P2000T games like most people did back in the day. This way of playing works best when the core is in **'Game Focus'** mode, like explained above. 2. Using both **Keyboard** and **Joypad** Use the **Keyboard** to answer the game's Yes/No questions and for things like entering the number of players or typing your name for the highscore list. Then switch to the **Joypad** during actual game play. This way of playing also works best when the core is in **'Game Focus'** mode. 3. Using **Joypad only.** This requires the use of the On-Screen Key Selector to enter the number of players or to answer Y/N questions. See the description below on how to use the On-Screen Key Selector. For this way of playing the core doesn't have to be in **'Game Focus'** mode. #### On-Screen Key Selector The On-Screen Key Selector lets you simulate key presses using your Joypad controller. This allows you to play almost all P2000T games without the need of an actual keyboard. Next to the regular Joypad mappings (for the Navigation keys + Space to fire), most games will ask simple Yes/No questions or allow you to enter your name in a high score list. The On-Screen Key Selector is activated by holding your Joypad's Left Bumper/Trigger/Shoulder button. Then with the D-pad you can loop through the keys and with the A/B button you then enter the highligted key. In the screenshot below you can see the On-Screen Key Selector in the bottom of the screen, where the player is about the enter the 'N' key to skip showing the "spelregels" (game rules): ![](../image/core/m2000/on-screen-key-selector.png) ## User 1 device types The M2000 core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): - **RetroKeyboard** - Keyboard. The keyboard inputs are always active. - **RetroPad** - Joypad. The buttons are internally mapped to actual keyboard key presses (see information below). ## Joypad | RetroPad Inputs | P2000T Keys | |---------------------------------------------|------------------------| | ![](../image/retropad/retro_a.png) | Space / Fire | | ![](../image/retropad/retro_b.png) | Space / Fire | | ![](../image/retropad/retro_start.png) | < START > | | ![](../image/retropad/retro_select.png) | < STOP > | | ![](../image/retropad/retro_dpad_up.png) | Up | | ![](../image/retropad/retro_dpad_down.png) | Down | | ![](../image/retropad/retro_dpad_left.png) | Left | | ![](../image/retropad/retro_dpad_right.png) | Right | | ![](../image/retropad/retro_l1.png) | On-Screen Key Selector | | ![](../image/retropad/retro_l2.png) | On-Screen Key Selector | ### Joypad remapping for games that use alternative keys Some P2000T games use alternative keys for navigation. An example is Fraxxon, which uses the **Left** and **Up** keys to move the spaceship horizontally, which was probably done for better playability on the original P2000T keyboard. To be able to use the D-pad for horizontal movement in the emulator, you should start Fraxxon, then open the menu and go to **Quick Menu > Controls > Port 1 Controls** and remap **D-Pad Right** to RetroPad **Up**. Now return to **Quick Menu > Controls**, click **Manage Remap Files** and select **Save Game Remap File** to save the joypad remapping for Fraxxon only. ## Keyboard ### Symbolic key mapping The M2000 core is using **symbolic** key mapping by default, which means that - where possible - keys on the PC keyboard are mapped to corresponding P2000T keys that show the same symbol, so you basically get the key which you pressed. The special keys < START >, < STOP > and < ZOEK > are mapped as follows: | RetroKeyboard Inputs | P2000T Keys | |---------------------------|----------------------| | F1 | < START > | | F2 | < STOP > | | F3 | < ZOEK > | | Shift + Numpad 1 | < ZOEK > | | Shift + Numpad 3 | < START > | | Shift + Numpad Enter | < STOP > | ### Positional key mapping Optionally, the M2000 core supports **positional** key mapping, which maps every key from a "real" keyboard to the key which has the same position/location on a P2000T keyboard. As the layout of a P2000T keyboard differs from modern keyboards, this might cause some unexpected mappings. So below you can see how the keys on the RetroKeyboard map to positional keys on the P2000T keyboard: | RetroKeyboard Inputs | P2000T Keys | |---------------------------|----------------------| | a .. z | a .. z | | A .. Z | A .. Z | | 0 .. 9 | 0 .. 9 | | Shift + 1 | Exclaim ! | | Shift + 2 | Double Quote " | | Shift + 3 | Pound & | | Shift + 4 | Dollar $ | | Shift + 5 | Percent % | | Shift + 6 | Ampersand & | | Shift + 7 | Quote ' | | Shift + 8 | Left Parenthesis ( | | Shift + 9 | Right Parenthesis ) | | Shift + 0 | Equals = | | Minus - | Minus - | | Underscore _ | Dash — | | Equals = | One Quarter ¼ | | Plus + | Three Quarters ¾ | | Left Bracket [ | At @ | | Left Curly Brace { | Arrow Up ↑ | | Right Bracket ] | Arrow Right → | | Right Curly Brace } | Arrow Left ← | | Backslash \ | Hash # | | Pipe \| | Block █ | | Semicolon ; | Semicolon ; | | Colon : | Plus + | | Quote ' | Colon : | | Double Quote " | Asterisk * | | Comma , | Comma , | | Period . | Period . | | Slash / | Slash / | | Question ? | Question ? | | Delete | Less < | | Shift + Delete | Greater > | | Backspace | Backspace | | Return | Enter | | Space | Space | | Backquote ` | < CODE > | | Tab | Tab | | Caps Lock | Shift Lock | | Left Shift | Left Shift | | Right Shift | Right Shift | | Up | Up | | Down | Down | | Right | Right | | Left | Left | | Numpad 0 .. 9 | 0 .. 9 | | Numpad Period . | Double Zero 00 | | Numpad Enter | Period . | | Numpad Multiply * | Clear Line | | Shift + Numpad Multiply * | Clear Page | | Shift + Numpad 1 | < ZOEK > | | Shift + Numpad 3 | < START > | | Shift + Numpad Enter | < STOP > | | F1 | < START > | | F2 | < STOP > | | F3 | < ZOEK > | ## External Links - [Libretro M2000 Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/m2000_libretro.info) - [Official M2000 Github Repository](https://github.com/p2000t/M2000) - [Report M2000 Issues Here](https://github.com/p2000t/M2000/issues) - [Wikipedia page on the Philips P2000T](https://en.wikipedia.org/wiki/Philips_P2000#P2000T) - [P20000T documentation](https://github.com/p2000t/documentation) - [P20000T game collection](https://github.com/p2000t/software/tree/master/cassettes/games) ================================================ FILE: docs/library/mame2003_plus.md ================================================ # MAME 2003-Plus ## Background MAME 2003-Plus (also referred to as MAME 2003+ and mame2003-plus) is a libretro multi-arcade system emulator core which prioritizes 1) usability and frontend integration, 2) performance, and 3) compatibility across the range of libretro-supported platforms including mobile devices, single board computers, and consoles. MAME 2003-Plus is part of a long tradition in arcade emulation of producing platform-specific and performance-optimized MAME builds. !!! Question "Why is it called **Plus**?" Unlike the other 'historic' libretro MAME cores which remain fixed at one MAME version, MAME 2003-Plus is actively maintained and has to date added support for hundreds of new games along with dozens of new features. MAME 2003-Plus is part of a lineage of codebase forks and ports: this core was forked from MAME 2003, which is itself derived from Xmame 0.78, the X11/Unix port of MAME 0.78. **Authors**: MAMEdev, MAME 2003-Plus team, et al (see [LICENSE.md](https://raw.githubusercontent.com/libretro/mame2003-plus-libretro/master/LICENSE.md) and [CHANGELOG.md](https://raw.githubusercontent.com/libretro/mame2003-plus-libretro/master/CHANGELOG.md)) ## Contribute to this documentation In order to propose improvements to this document, [visit it's corresponding source page on github](https://github.com/libretro/docs/blob/master/docs/library/mame2003-plus.md). Changes are proposed using "Pull Requests." ## See also [MAME 2003](mame_2003.md) ## License [MAME Non-Commercial](https://raw.githubusercontent.com/libretro/mame2003-libretro/master/LICENSE.md) ## Extensions zip, chd !!! Note "CHD paths" Some games require data from an internal hard drive, CD-ROM, laserdisk, or other media in order to be emulated -- those forms of media are packaged as CHD files. CHD files should be copied to subfolders within the folder where the romset zips have been installed: `/libretro content dir/blitz/blitz.chd` ## Building romsets for MAME 2003-Plus MAME 2003-Plus began with the game drivers from MAME 0.78, meaning that 95% or more of MAME 0.78 romsets will work as-is in MAME 2003-Plus, where they immediately benefit from its bugfixes and other improvements. **In order to play the new games and games which received ROM updates in MAME 2003-Plus, you will need to find or build MAME 2003-Plus romsets.** !!! question "What is a romset?" Arcade games are packaged as zip files, most of which are composed of more than one individual 'ROM' files. That is why some resources inaccurately refer to an individual arcade game as a ROM (like people use to describe a zipped game cartridge ROM) while other resources refer to an individual game as a **ROM set**, **ROMset**, or **romset**. MAME 2003-Plus has the ability to generate an XML "DAT" file directly from the [MAME menu](#MAME-menu). ### Step 1: Obtaining an XML DAT DAT files describe the exact ROM contents that the emulator needs including filenames, file sizes, and checksums to verify contents are not incorrect or corrupt. mame2003-plus has the ability to generate an XML "DAT" file from the MAME Menu. You can also access the MAME menu by turning it on as a core option, selecting **Generate XML DAT** and then disabing the menu as a core option. ### Step 2: Finding a source for ROMs In order to build a complete MAME 2003-Plus collection, the ingredients are: * A complete MAME 0.223 or later romset collection * A complete MAME 0.223 or later "rollback" romset collection * MAME 0.78 CHD collection * The NeoGeo UniBIOS 3.3, freely available at http://unibios.free.fr/ ### Step 3: Building MAME 2003-Plus romsets Refer to [Validating, Rebuilding, and Filtering ROM Collections](https://github.com/RetroPie/RetroPie-Setup/wiki/Validating,-Rebuilding,-and-Filtering-ROM-Collections) for details on how to configure ClrMamePro to use your sources as "rebuild" folders. We recommend the **Full Non-Merged** format, where each romset zip files includes all the files needed to run each game, including any ROMs from 'parent' ROM sets and BIOS sets. To configure ClrMamePro to validate or rebuild a Full Non-Merged collection, use "Non-Merged" mode and disable "Separate BIOS Sets" from the "Advanced" menu in both ClrMamePro's Rebuild and Scanner menus. !!! tip A complete **Full Non-Merged** romset collection with CHDs and Samples only requires approximately 6% more storage space than the **Split** format romsets that are also sometimes used to structure arcade romsets. MAME 2003-Plus can read **Split, TorrentZipped** romsets, but the RetroArch playlist scanner only supports **Full Non-Merged, TorrentZipped** romsets for MAME 2003-Plus. #### Recommended ClrMamePro settings ClrMamePro remains the most popular tool for rebuilding MAME romsets, at least for now. That said, ClrMamePro is focused on supporting more recent MAME versions so there are at least two things to know if you are using ClrMamePro to generate a MAME 2003-Plus set: 1. If you are scanning CHDs, go to `Settings` -> `Compressor` -> `CHDMan` tab and change `Req. CHD Version` to `3`. 2. If you are using the suggested setting of `Disable Separate BIOS Sets` then ClrMamePro will report the BIOS romset files as missing even though you told the program you don't want them. mame2003-plus incorporates 15 different kinds of BIOS romsets, so it is normal to see a ClrMamePro message like this after a clean and complete scan: `You are missing 15 of 4831 known mame2003-plus.xml sets (+ BIOS sets)` ### Sourcing CHDs MAME 2003-Plus uses exactly the same MAME 0.78 CHDs (CHD v3) as MAME 2003. ## BIOS BIOS romsets are not needed when using "Full Non-Merged" arcade romsets. For "Split" and "Non-Merged" romsets, place the BIOS in the same directory as the game romset. ## Features | Feature | Supported | |-------------------|-----------| | Saves | ✔ | | States | game-dependent | | Rewind | ✔ | | Netplay | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✔ | | Controllers | ✔ | | Multi-Mouse | ✔ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | ## Input system, controls, and options mame2003-plus emulates thousands of games, many of which have unique control layouts. These games are emulated on more than a thousand variations of arcade hardware. The purpose of the input system is to communicate input from the user's physical controls through the libretro frontend, the mame2003-plus emulator core, and into the emulated game itself. No system of default input mappings can address the full range of emulated games and supported controls. Some degree of per-game customization should ways be expected. However, to the extent possible it is also within the purpose of the MAME 2003-Plus input system to attempt to provide predictable and meaningful defaults for input across this wide range. ## Default RetroPad Layouts | **Classic Gamepad** | |---------------------| | The **Classic Gamepad** is based on mainline MAME's default Xbox 360 controller layout and is also likely to suit DualShock or SNES-style gamepads. The corresponding option in configuration file is ```input_libretro_device_pX = "1"``` (where X is the player number, ```input_libretro_device_p1 = "1"``` for player 1, etc.).
![Xbox 360-style RetroPad](../image/controller/xbox360.png)
![PSX DualShock-style RetroPad](../image/controller/psx.png) | | **Modern Fightstick** | |-----------------------| | The **Modern Fightstick** layout is the fight stick and pad layout popularized by Street Fighter IV and assumes an 8+ button controller. The corresponding option in configuration file is ```input_libretro_device_pX = "257"``` (where X is the player number, ```input_libretro_device_p1 = "257"``` for player 1, etc.). Gamepad can also serve as an alternative Xbox/PSX-style layout for Street Fighter 2.
For arcade control panels, **Modern Fightstick** can be mapped in this way:
![Modern Fightstick mapping for arcade controls](../image/core/mame2003-plus/fightstick.png)| | **6-Button** | |--------------| | **6-button** is a layout intended for SNES-type RetroPad controls as well as 6-button arcade panels arcade panels. The corresponding option in configuration file is ```input_libretro_device_pX = "769"``` (where X is the player number, ```input_libretro_device_p1 = "769"``` for player 1, etc.). **6-button** can be mapped in this way:
![6-button mapping for arcade controls](../image/core/mame2003-plus/6button.png)| | **8-Button** | |--------------| |**8-button** is a layout intended for an arcade panel. The corresponding option in configuration file is ```input_libretro_device_pX = "513"``` (where X is the player number, ```input_libretro_device_p1 = "513"``` for player 1, etc.). **8-button** is configured like this
![8-button mapping for arcade controls](../image/core/mame2003-plus/8button.png)| ### Keyboard Input `mame_keyboard` sets the core to process keyboard input directly through the legacy "MAME" keyboard interface. Use this input mode only if your input device is seen as a keyboard, including some arcade control panel hardware. ### Mouse and trackball support MAME 2003-Plus has support for multiple mice or touch devices in games that support trackballs, etc. MAME 2003-Plus also supports one or two spinners/dials via the "Share 2 player dial controls across one X/Y device" core option. By default, mice/trackballs and analog sticks (the left one, for controllers with 2) are supported in games that would have them, or equivalents. For example, Centipede supports the mouse/trackball, and Afterburner supports the stick. ### Pointer, trackpad, touchscreen support Absolute pointer devices are supported, but need to be turned on via the corresponding core option. ### Lightgun support Because MAME 2003-Plus does not yet implement the libretro lightgun API, the core currently supports lightguns only if they are configured to emulate a mouse. ### 2-player dial and spinner devices 2-player spinner and dial devices can be represented as 1 device with 2 axes. MAME 2003-Plus can be configured to share this device across both players: Player 1 = X axis, Player 2 = Y axis. This can be enabled via a setting in the `retroarch-core-options.cfg` file: ```mame2003-plus-dialsharexy = "enabled"``` !!! Warning Enabling this option will disable standard mouse support. ### Analog and digital controller support MAME 2003-Plus natively supports analog and digital controls. ### 4-way joystick simulation 4-way joysticks are an essential aspect of the gameplay for many iconic arcade titles including games like Donkey Kong, Pac-Man, and Q-Bert. Because modern joysticks generally use 8-way designs, it is usually impossible to play these games well without special hardware. MAME 2003-Plus includes a core option to simulate 4-way joysticks. When enabled, this logic analyzes input from 8-way digital joysticks in order to render its position as if the joystick had a 4-way design. This simulation is not the same as using a real 4-way joystick, but it can make a significant improvement to playability. ### Content-aware control names In the same way that content-aware core options only appear when they are relevant to the current game, MAME 2003-Plus has added support for content-aware control names. In other words, when remapping Street Fighter 2 controls, the libretro frontend can display the control names that were printed on the real arcade control panel like `Jump`, `Strong Punch` and `Forward Kick` instead of a generic labels like `Up`, `Button 1`, `Button 2`, etc. Because support for control names is relatively new and is derived from the third-party **controls.dat** project, control names need to be verified by a human being before they are activated. As of end end of 2018, dozens of games have these active control names, but hundreds more need to be double-checked before being enabled. [Coders, and users who are willing to learn basic github commands, are invited to join in this effort](https://github.com/libretro/mame2003-plus-libretro/wiki/Submitting-Button-Names). ----------- ## Other key features ## Audio samples Some games require an additional zip file with recorded sounds or music in order for audio to work correctly. Audio 'sample' files should be placed in a `samples` subdirectory within `/libretro system dir/mame2003-plus/`. !!! tip "Alternate CD soundtrack support" MAME 2003-Plus also supports alternate soundtracks for several popular arcade titles that were also released in other formats with high quality audio soundtracks. Alternate soundtracks are supported for **Double Dragon**, **Final Fight**, **Mortal Kombat**, **Michael Jackson’s Moonwalker**, **NBA Jam**, and **Out Run**. ### Backdrop artwork Some games require backdrop artwork files in order to be fully emulated. Because RetroArch, the reference libretro frontend, does not yet incorporate support for so-called "backdrop" artwork, the MAME 2003-Plus github repository includes [a folder of high-resolution backdrop artwork](https://github.com/libretro/mame2003-plus-libretro/tree/master/metadata/artwork) that is compatible with the core's built-in artwork display system. These artwork `zip` files should be placed within `/libretro system dir/mame2003-plus/artwork`. ![Armor Attack with backdrop artwork](../image/core/mame2003-plus/armor-attack-backdrop-artwork.jpg) _"Armor Attack" backdrop artwork pack prepared by UDB23_ ### Run Ahead input lag reduction This core supports the RetroArch "Run Ahead" input latency reduction feature when Run Ahead is set to `Second Instance`, but as of the end of 2018 there are [known issues preventing Run Ahead from functioning properly and a bounty fundraiser to fix them](https://github.com/libretro/mame2003-plus-libretro/issues/434). ### MAME Menu The simplest way to access the "MAME menu" is by enabling it in the core options. If your input mode is set to allow input to the `mame_keyboard` interface, you can also enter the menu by pressing the `Tab` key. ### Dip-switches Many arcade games have hardware switches for arcade owners to modify certain parameters which can be adjusted by accessing the MAME menu and selecting the '**Dip Switches**' option. Dip switches often controlled features like free play (no coins needed), difficulty level, and cocktail table cabinet rotation mode. ### Service menu For games where dip switches are not available directly within the MAME menu, MAME 2003-Plus the core can often access a game's internal servic menus to set options by pressing `F2` with a keyboard while `mame_keyboard` or `simultaneous` input mode is enabled. ### High scores The **hiscore.dat** is compiled into MAME 2003-Plus and then spawned into `/libretro system dir/mame2003-plus/` the first time the core is run. Users do not need to install the **hiscore.dat** themselves. From then on, users can modify or replace this file with their own custom DAT if they choose. When high scores are saved, they are either stored as NVRAM data in `libretro system dir/mame2003-plus/nvram/` or as hiscore data in: `libretro system dir/mame2003-plus/hi/` ### Cheats MAME 2003-Plus supports the MAME cheat engine, allowing you to use the MAME menu to enable various in-game cheats. To activate these, there is a necessary supplementary file called `cheat.dat`. This file can be [downloaded from the MAME 2003-Plus 'metadata' repository](https://github.com/libretro/mame2003-plus-libretro/tree/master/metadata). Place `cheat.dat` in: `libretro system dir/mame2003-plus/`. ### History DAT MAME 2003-Plus supports the use of the **history.dat** file, which displays background information about many games from within the **MAME Menu**. This file can be [downloaded from the MAME 2003-Plus 'metadata' repository](https://github.com/libretro/mame2003-plus-libretro/tree/master/metadata). Place `history.dat` in: `libretro system dir/mame2003-plus/ `. ### LED output system As of late 2018, MAME 2003-Plus incorporates preliminary support for the libretro LED lighting output system. Documentation is yet to be written on this topic. ----------- ## Core-generated content Core-generated content is placed in sub-directories within `/libretro savefile dir/mame2003-plus/`: ``` /libretro savefile dir/mame2003-plus/diff/ /libretro savefile dir/mame2003-plus/nvram/ /libretro savefile dir/mame2003-plus/hi/ /libretro savefile dir/mame2003-plus/cfg/ /libretro savefile dir/mame2003-plus/memcard/ ``` ----------- ## Core options !!! Tip **Restart core** indicates that the core must be restarted in order for changes to that option to take effect. !!! Tip "Content-aware core options" Because MAME 2003-Plus supports more than 4,000 games, there are a number of core options which only apply to a subset of its library. For example, there are several options to configure vector displays which have no effect for games with any other kind of display. **MAME 2003-Plus only presents core options to the frontend that are relevant to the game that is currently loaded** In other words, the vector options only appear when a vector game is currently loaded. | Core option | Description| | --- | --- | | 4-way joystick emulation on 8-way joysticks | See **4-way joystick simulation** section of this doc. ```mame2003-plus_four_way_emulation = "enabled|disabled"``` | | Mouse Device | Set mouse device input to be read either from a mouse, a pointer (pointer, trackpad, touchscreen), or to be disabled. ``` mame2003-plus_mouse_device = "mouse|pointer|disabled"``` | | Show Lightgun crosshair | Toggle crosshair visibilty for lightgun games. ```mame2003-plus_crosshair_enabled = "enabled|disabled"``` | |Skip Disclaimer| Skip the copyright disclaimer message. ```mame2003-plus_skip_disclaimer = "disabled|enabled"``` | |Skip Warnings| _Advanced feature: changing from the default is not recommended in most cases._ Skip any driver warnings about emulation quality. ```mame2003-plus_skip_warnings = "disabled|enabled"``` | |Display MAME menu | Enable this core option to display the core's **MAME Menu** and then disable it when you have finished using the **MAME Menu**. ```mame2003-plus_display_setup = "disabled|enabled"``` | |Specify Neo Geo BIOS (Restart core) | Manually specify your choice of Neo Geo BIOS from among those supported. ```mame2003-plus_neogeo_bios = "default|euro|euro-s1|us|us-e|asia|japan|japan-s2|unibios33|unibios20|unibios13|unibios11|unibios10|debug|asia-aes"``` | |Specify Sega ST-V BIOS (Restart core) | Manually specify your choice of ST-V BIOS from among those supported. ```mame2003-plus_stv_bios = "default|japan|japana|us|japan_b|taiwan|europe"``` | |Use CD soundtrack (Restart core) | See **Alternate CD soundtrack support** in the **Audio samples** section of this doc. ```mame2003-plus_use_alt_sound = "enabled|disabled"``` | |Share 2 player dial controls across one X/Y device | See the **2-player dial and spinner devices** section of this doc. ```mame2003-plus_dialsharexy = "disabled|enabled"``` | |Vector resolution multiplier (Restart core)| Attempts to create a higher quality emulation of vector display hardware by upscaling the emulated display to a higher resolution. ```mame2003-plus_vector_resolution = "1024x768|640x480|1280x960|1440x1080|1600x1200|original"``` | |Vector antialiasing| Enables or disables the **anti-aliasing** for vector games. ```mame2003-plus_vector_antialias = "enabled|disabled"``` | |Vector beam width | Sets the emulated width of the vector beam in pixels. This setting is only effective when **anti-aliasing** is enabled. ```mame2003-plus_vector_beam_width = "2|1|1.2|1.4|1.6|1.8|2.5|3|4|5|6|7|8|9|10|11|12"``` | |Vector translucency| Emulates the partial transparency of vector display hardware. | |Vector flicker| Emulates the flicker of vector display hardware. ```mame2003-plus_vector_flicker = "20|0|10|30|40|50|60|70|80|90|1001.5|0.5|1|2|2.5|3"``` | |Vector intensity| Emulates the variable intensity of vector display hardware. ```mame2003-plus_vector_intensity = "1.5|0.5|1|2|2.5|3"``` | |DCS Speedhack| _Advanced feature: changing from the default is not recommended in most cases._ Use so-called "speed hacks" to improve the performance of DCS sound hardware. ```mame2003-plus_dcs_speedhack = "enabled|disabled"``` | |Locate system files within a subfolder | For historical reasons, MAME 2003-Plus reads system files within a subfolder named `mame2003-plus` even though this is not part of the libretro API. ```mame2003-plus_core_sys_subfolder = "enabled|disabled"```| |Locate save files within a subfolder | For historical reasons, MAME 2003-Plus saves files within a subfolder named `mame2003-plus` even though this is not part of the libretro API. ```mame2003-plus_core_save_subfolder = "enabled|disabled"``` | |TATE Mode| From the Japanese 縦 (ta-te) meaning "vertical", **TATE Mode** renders vertical games lengthwise along the display. This mode is intended for use with rotating monitors and portable devices that can make the full use of their viewable area for games which used vertical monitors. ```mame2003-plus_tate_mode = "disabled|enabled"```| |Brightness| Simple brightness adjustment. ```mame2003-plus_brightness = "1.0|0.2|0.3|0.4|0.5|0.6|0.7|0.8|0.9|1.1|1.2|1.3|1.4|1.5|1.6|1.7|1.8|1.9|2.0"``` | | Gamma correction | Simple gamma adjustment. ```mame2003-plus_gamma = "1.0|0.5|0.6|0.7|0.8|0.9|1.1|1.2|1.3|1.4|1.5|1.6|1.7|1.8|1.9|2.0"``` | |Frameskip| _Advanced feature: changing from the default is not recommended in most cases._ ```mame2003-plus_frameskip = "0|1|2|3|4|5"``` | |Sample Rate (KHz)| _Advanced feature: changing from the default is not recommended in most cases._ ```mame2003-plus_sample_rate = "48000|8000|11025|22050|30000|44100"```| |Input interface | _Advanced feature: changing from the default is not recommended in most cases._ **retropad**, the default option, processes input via the libretro retropad abstraction, including from any keyboard which are bound to the retropad. The **keyboard** setting only sends keyboard input directly to the core, ignoring the retropad. The **simultaneous** setting sends inputs both ways at the same time and is not recommended. This setting exists for historical reasons. ```mame2003-plus_input_interface = "retropad|keyboard|simultaneous"``` | |Legacy Remapping | _Note: Using the legacy MAME control remapper may affect stateless netplay between two users with their MAME remappings set differently._ ```mame2003-plus_mame_remapping = "enabled|disabled"``` | |Display artwork (Restart core) | Display artwork packs from within the core, particularly "backdrop" artwork. ```mame2003-plus_display_artwork = "enabled|disabled"``` | |Artwork resolution multiplier (Restart core)| Upscales games with artwork backs so that the artwork can be displayed at a higher resolution. ```mame2003-plus_art_resolution = "1|2"``` | |NVRAM Bootstraps | _Advanced feature: changing from the default is not recommended in most cases._ ```mame2003-plus_nvram_bootstraps = "enabled|disabled"```| |Dip switch/Cheat input ports| _Advanced feature: changing from the default is not recommended in most cases._ Activates a few specific cheats that manipulate the dipswitch input system. ```mame2003-plus_cheat_input_ports = "disabled|enabled"``` | |Bypass audio skew (Restart core) | _Advanced feature: changing from the default is not recommended in most cases._ Bypass the frontend's "audio skew" feature which attempts to adjust the audio for games which displayed at framerates not native to modern displays. ```mame2003-plus_machine_timing = "enabled|disabled"``` | |Center joystick axis for digital controls | Emulates the center position of an analog joystick to allow digital joysticks to play analog based games. This is only applied when the AD Stick type is used. ```mame2003-plus_digital_joy_centering = "enabled|disabled"``` | ----------- ## External Links * [MAME 2003-Plus Github Repository](https://github.com/libretro/mame2003-plus-libretro) ### See also - [MAME 2003](mame_2003.md) - [MAME 2010](mame_2010.md) - [SAME_CDI](same_cdi.md) ================================================ FILE: docs/library/mame_2003.md ================================================ # MAME 2003 ## Background MAME 2003 is a libretro arcade system emulator core originally derived from xmame 0.78. This core is a popular choice for the Raspberry Pi family and other low-powered hardware because it supports most 2D-era arcade games and a broad set of features without requiring as much processor and memory resources as later MAME cores. Author(s): MAMEdev ## Contribute to this documentation In order to propose improvements to this document, [visit it's corresponding source page on github](https://github.com/libretro/docs/blob/master/docs/library/mame2003.md). Changes are proposed using "Pull Requests." ## See also MAME 2000, [MAME 2003-Plus](mame2003_plus.md), MAME 2010, MAME 2014, MAME 2016, and MAME. ## License [MAME Non-Commercial](https://raw.githubusercontent.com/libretro/mame2003-libretro/master/LICENSE.md) ## Extensions zip ## BIOS BIOS romsets are not needed when using "Full Non-Merged" arcade romsets. For "Split" and "Non-Merged" romsets, place the BIOS in the same directory as the game romset. ## Features | Feature | Supported | |-------------------|:---------:| | Saves | ✔ | | States | game-dependent | | Rewind | ✔ | | Netplay | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✔ | | Controllers | ✔ | | Multi-Mouse | ✔ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | ### Core options - **Frameskip** (**0**-5): Skips frame to make slow emulation look faster than it is while compromising playability. (Not advised) - **DCS Speedhack** (**On**/Off): Speedhack for the Midway sound hardware used in Mortal Kombat 2, 3 and others. Improves performance in these games. - **Skip Disclaimer** (**On**/Off): Skips the 'nag-screen'. - **Skip Warnings** (On/**Off**): Skips the warning screen shown before games with incomplete emulation. - **Samples** (**On**/Off): Requires valid sample zip files. | - | - **Sample Rate** (11025-**48000**): Lowering may improve performance on weaker devices. - **Cheats** (On/**Off**): Requires a valid cheat.dat file. - **Share 2 player dial controls across one X/Y device** (On/**Off**): Some dial/spinner hardware are actually one device with one axis for each player. This supports that setup, by breaking down the normal mouse x/y into two seperate inputs. - **Mouse Device** (**mouse**/pointer/disabled): Switch between mouse (e.g. hardware mouse, trackball, etc), pointer (touchpad, touchscreen, lightgun, etc), or disabled. - **TATE Mode** (On/**Off**): Enable if rotating display for vertically oriented games (Pac-Man, Galaga, etc). Requires `video_allow_rotate = "false"` setting in RetroArch.cfg or core override file. ----------- ## Directories * Some MAME games require data from an internal hard drive, CD-ROM, laserdisk, or other media in order to be emulated -- those forms of media are packaged as CHD files. CHD files should be copied to subfolders within the folder where the MAME ROM zips have been installed. e.g.: ``` /libretro content dir/blitz/blitz.chd ``` * Some games require an additional zip file with recorded sounds or music in order for audio to work correctly. Audio 'sample' files should be placed in subdirectories within `/libretro system dir/mame2003/` e.g.: ``` /libretro system dir/mame2003/samples/ ``` * Cheat and history metadata files should be moved from github's [`/libretro/mame2003-libretro/tree/master/metadata`](https://github.com/libretro/mame2003-libretro/tree/master/metadata) and placed within `/libretro system dir/mame2003/` e.g.: ``` /libretro system dir/mame2003/cheat.dat /libretro system dir/mame2003/history.dat ``` * User-generated content is placed in sub-directories within `/libretro savefile dir/mame2003/` e.g.: ``` /libretro savefile dir/mame2003/diff/ /libretro savefile dir/mame2003/nvram/ /libretro savefile dir/mame2003/hi/ /libretro savefile dir/mame2003/cfg/ /libretro savefile dir/mame2003/memcard/ ``` ### MAME menu To access the MAME internal menu, press the 'TAB' key or RetroPad R2. If you rebind MAME global inputs ('Input (general)'), it will update a file in `/libretro savefile dir/mame2003/cfg/` **default.cfg**. Note: If you rebind MAME global inputs ('Input (general)'), it will update a file in `/libretro savefile dir/mame2003/cfg/` **default.cfg**. ## Controllers The core supports one controller setting(s): * RetroPad | MAME 2003 | [RetroPad](RetroPad) | |--------------------------------------|----------------------------------------------| | Button 1/Right Stick Down/UI Cancel | ![](../image/retropad/retro_b.png) | | Button 2/Right Stick Left | ![](../image/retropad/retro_y.png) | | Coin in | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | Left Joystick | ![](../image/retropad/retro_dpad.png) | | Button 4/Right Stick Right/UI Select | ![](../image/retropad/retro_a.png) | | Button 3/Right Stick Up | ![](../image/retropad/retro_x.png) | | Button 5 | ![](../image/retropad/retro_l1.png) | | Button 6 | ![](../image/retropad/retro_r1.png) | | Button 7 | ![](../image/retropad/retro_l2.png) | | Button 8/TAB Menu | ![](../image/retropad/retro_r2.png) | | Button 9 | ![](../image/retropad/retro_l3.png) | | Button 10 | ![](../image/retropad/retro_r3.png) | | Left Joystick | ![](../image/retropad/retro_left_stick.png) | | | ![](../image/retropad/retro_right_stick.png) | ## MAME 2003 Features ### Service menu MAME 2003 can ability to access games' internal service menus to set permanent game options. This allows you to, for example, configure a game to be 'free play' (no need to insert coins). To access the MAME service, press the 'F2' key. After changing options in the service mode, the game's internal memory will be stored to an .nv file in: `/libretro savefile dir/mame2003/nvram/` ### Dip-switches Similarly to the [Service menu](#service-menu), many arcade games had hardware switches for arcade owners to modify certain parameters. These can be adjust by pressing the 'TAB' key to access the MAME menu, and select the '**Dip Switches**' option. Here you can turn them on/off. ### High scores When high scores are saved, they are either stored as NVRAM data in `libretro system dir/mame2003/nvram/` or as hiscore data in: `libretro system dir/mame2003/hi/` ### Save states MAME 2003-Plus supports save states for many, but not all games. ### Cheats MAME 2003-Plus supports the MAME cheat engine, allowing you to use the MAME menu to enable various in-game cheats. To active these, there is a necessary supplementary file called `cheat.dat`. This file can be [downloaded from the MAME 2003 'metadata' repository](https://github.com/libretro/mame2003-libretro/tree/master/metadata). Place `cheat.dat` in: `libretro system dir/mame2003-plus/` Additionally, the 'enabled cheats' core option needs to be turned on. This option is is called: `mame2003-cheats = "enabled"` ----------- ## Mouse/Trackball/Analog Controller support MAME 2003 has support for multiple mice or touch devices in games that support trackballs, etc. MAME 2003 also supports one or two spinners/dials via the "Share 2 player dial controls across one X/Y device" core option. By default, mice/trackballs and analog sticks (the left one, for controllers with 2) are supported in games that would have them, or equivalents. For example, Centipede supports the mouse/trackball, and Afterburner supports the stick. Lightgun games are supported by either. The left and right mouse buttons can be bound to fire/etc using the MAME menu. ### Pointer/Trackpad/Touchscreen support Absolute pointer devices are supported, but need to be turned on via a setting in the retroarch-core-options.cfg file. mame2003-mouse_device = "pointer" ### 2 player dial/spinner devices 2 player spinner/dial devices can be represented as 1 device with 2 axes. mame2003 can be configured to share this device across both players: Player 1 = X axis, Player 2 = Y axis. This can be enabled via a setting in the retroarch-core-options.cfg file, found in: mame2003-dialsharexy = "enabled" NOTE: This will disable Mouse support. ## Dual stick games The right analog stick can now be used a second joystick. This is enabled by default, via a setting in the retroarch-core-options.cfg file, found in: mame2003-rstick_to_btns = "enabled" ## Compatibility **The MAME 2003 core accepts MAME 0.78 ROMsets.** Each version of an arcade emulator must be used with ROMs that have the same exact version number. For example, MAME 0.37b5 ROMsets are required by the MAME 2000 emulator, but MAME 0.37b5 sets will not work correctly with the MAME 2003 or MAME 2010 emulator cores. Those cores require MAME 0.78 and MAME 0.139 ROM sets, respectively. File-not-found errors are the result of a ROMset that is wrong or incomplete, including if you're trying to run a "Split" clone .zip without the parent .zip present. Non-Merged MAME0.78 ROMsets do not require parent .zips to be present. ## External Links * [MAME 2003 Github Repository](https://github.com/libretro/mame2003-libretro) * [RetroPie MAME 2003 documentation](https://github.com/RetroPie/RetroPie-Setup/wiki/lr-mame2003) ### See also - [MAME 2003 Plus](mame2003_plus.md) - [MAME 2010](mame_2010.md) - [SAME_CDI](same_cdi.md) ================================================ FILE: docs/library/mame_2010.md ================================================ # Arcade (MAME 2010) ## Background MAME 2010 is a port of MAME 0.139 for libretro, originally sourced from https://github.com/mamedev/mame/releases/download/mame0139/mame0139s.zip The OSD code is inspired by other MAME ports : - mame2003: https://github.com/libretro/mame2003-libretro - ps3 mame0.125: http://www.volny.cz/molej/ps3/mame_ps3.htm - mame4droid: http://code.google.com/p/imame4all/source/browse/ ### Author/License MAME 2010 code is copyright [Nicola Salmoria and the MAME team](http://mamedev.org/) and distributed under a [Non-Commercial MAME license](https://raw.githubusercontent.com/libretro/mame2010-libretro/master/docs/license.txt). A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by MAME 2010 have the following file extensions: - `.zip` - `.7z` - `.chd` ## Databases RetroArch database(s) that are associated with the MAME 2010 core: - [MAME 2010](https://github.com/libretro/libretro-database/blob/master/rdb/MAME%202010.rdb?raw=true) ## BIOS BIOS files should either be placed in the same folder as the Arcade romset ZIP file, or should be incorporated into the Arcade romset ZIP file itself in a "Full Non-Merged" romset format. ## Features Frontend-level settings or features that the (Core name) core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | - | | States | - | | Rewind | - | | Netplay | - | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | - | | Native Cheats | - | | Controls | - | | Remapping | - | | Multi-Mouse | - | | Rumble | - | | Sensors | - | | Camera | - | | Location | - | | Subsystem | - | | [Softpatching](../guides/softpatching.md) | - | | Disk Control | - | | Username | - | | Language | - | | Crop Overscan | - | | LEDs | - | ### Directories MAME 2010 requires the following directories exist, and will create them if they are missing: - libretro system folder/mame2010/: location for cheat.zip cheats file - libretro system folder/mame2010/artwork: MAME bezels and overlay files - libretro system folder/mame2010/crosshairs: custom crosshair images - libretro system folder/mame2010/fonts: custom fonts - libretro system folder/mame2010/samples: audio sample zip files needed by some games - libretro saves folder/mame2010/cfg: automatically-generated MAME configuration files - libretro saves folder/mame2010/comment: MAME debugger comment files - libretro saves folder/mame2010/ctrlr: MAME controller customization files - libretro saves folder/mame2010/image: game image content - libretro saves folder/mame2010/ini: MAME.ini files - libretro saves folder/mame2010/input: Recorded input files - libretro saves folder/mame2010/memcard: Save folder for emulated memcard device memory - libretro saves folder/mame2010/nvram: Save folder for emulated nvram device memory ## Core options The MAME 2010 core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Mouse supported** (disabled|enabled) - **Video approach 1 Enabled** (disabled|enabled) - **Hide game info screen** (disabled|enabled) - **Hide warning screen** (disabled|enabled) - **Core provided aspect ratio** (DAR|PAR) - **Enable autofire** (disabled|button 1|button 2|R2 to button 1 mapping|R2 to button 2 mapping) - **Set autofire pulse speed** (medium|slow|fast) - **Set frameskip** (0|1|2|3|4|automatic) - **Set sample rate** (Restart)** (48000Hz|44100Hz|32000Hz|22050Hz) - **Set brightness** (default|+1%|+2%|+3%|+4%|+5%|+6%|+7%|+8%|+9%|+10%|+11%|+12%|+13%|+14%|+15%|+16%|+17%|+18%|+19%|+20%|-20%|-19%|-18%|-17%|-16%|-15%|-14%|-13%|-12%|-11%|-10%|-9%|-8%|-7%|-6%|-5%|-4%|-3%|-2%|-1%) - **Set contrast** (default|+1%|+2%|+3%|+4%|+5%|+6%|+7%|+8%|+9%|+10%|+11%|+12%|+13%|+14%|+15%|+16%|+17%|+18%|+19%|+20%|-20%|-19%|-18%|-17%|-16%|-15%|-14%|-13%|-12%|-11%|-10%|-9%|-8%|-7%|-6%|-5%|-4%|-3%|-2%|-1%) - **Set gamma** (default|+1%|+2%|+3%|+4%|+5%|+6%|+7%|+8%|+9%|+10%|+11%|+12%|+13%|+14%|+15%|+16%|+17%|+18%|+19%|+20%|-20%|-19%|-18%|-17%|-16%|-15%|-14%|-13%|-12%|-11%|-10%|-9%|-8%|-7%|-6%|-5%|-4%|-3%|-2%|-1%) - **Use external hiscore.dat** (disabled|enabled) ## Controllers MAME 2010 supports keyboard use and up to four joypads. RetroPad MAME Equivalent RETRO_DEVICE_ID_JOYPAD_START [KEY_START] RETRO_DEVICE_ID_JOYPAD_SELECT [KEY_COIN] RETRO_DEVICE_ID_JOYPAD_A [KEY_BUTTON_1] RETRO_DEVICE_ID_JOYPAD_B [KEY_BUTTON_2] RETRO_DEVICE_ID_JOYPAD_X [KEY_BUTTON_3] RETRO_DEVICE_ID_JOYPAD_Y [KEY_BUTTON_4] RETRO_DEVICE_ID_JOYPAD_L [KEY_BUTTON_5] RETRO_DEVICE_ID_JOYPAD_R [KEY_BUTTON_6] RETRO_DEVICE_ID_JOYPAD_L2 [KEY_TAB] RETRO_DEVICE_ID_JOYPAD_R3 [KEY_F3] RETRO_DEVICE_ID_JOYPAD_L3 [KEY_F2] RETRO_DEVICE_ID_JOYPAD_UP [KEY_JOYSTICK_U] RETRO_DEVICE_ID_JOYPAD_DOWN [KEY_JOYSTICK_D] RETRO_DEVICE_ID_JOYPAD_LEFT [KEY_JOYSTICK_L] RETRO_DEVICE_ID_JOYPAD_RIGHT [KEY_JOYSTICK_R] #### Lightgun To be written for MAME 2010 | RetroLightgun Inputs | (Device name) Inputs | |--------------------------------------------------------|---------------------------| | ![](../image/retromouse/retro_mouse.png) Gun Crosshair | - | | Gun Trigger | - | | Gun Reload | - | | Gun Aux A | - | | Gun Aux B | - | | Gun Aux C | - | | Gun Start | - | | Gun Select | - | | Gun D-pad Up | - | | Gun D-pad Down | - | | Gun D-pad Left | - | | Gun D-pad Right | - | ## External Links - [MAME 2010 Github Repository](https://github.com/libretro/mame2010-libretro) - [MAMEdev](http://mamedev.org/) - [MAME 2010 Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mame2010_libretro.info) - [MAME 2010 README](https://github.com/libretro/mame2010-libretro/blob/master/README.md) - [Report MAME 2010 Issues Here](https://github.com/libretro/mame2010-libretro/issues) ### See also - [MAME 2003](mame_2003.md) - [MAME 2003 Plus](mame2003_plus.md) - [SAME_CDI](same_cdi.md) ================================================ FILE: docs/library/melonds.md ================================================ # Nintendo - DS (melonDS) ## Background An up-and-coming Nintendo DS emulator by Arisotura, ported to libretro. !!! warning "This is the older version!" This version of the melonDS core is obsolete and unmaintained. You are encouraged to migrate to [melonDS DS](melonds_ds.md), which is based on a newer version of the original emulator, has more features, and is easier to use. ### Author/License The melonDS core has been authored by - Arisotura The melonDS core is licensed under - [GPLv3](https://github.com/libretro/melonDS/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the melonDS core have the following file extensions: - .nds ## Databases RetroArch database(s) that are associated with the melonDS core: - [Nintendo - Nintendo DS](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%20DS.rdb) - [Nintendo - Nintendo DS Decrypted](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%20DS%20Decrypted.rdb) - [Nintendo - Nintendo DS (Download Play)](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%20DS%20(Download%20Play).rdb) ## BIOS Required or optional firmware files go in the frontend's `system` directory. | Filename | Description | md5sum | |:----------------:|:------------------------:|:--------------------------------:| | bios7.bin | NDS ARM7 BIOS - Optional | df692a80a5b1bc90728bc3dfc76cd948 | | bios9.bin | NDS ARM9 BIOS - Optional | a392174eb3e572fed6447e956bde4b25 | | firmware.bin | NDS Firmware - Optional | | | dsi_bios7.bin | DSi ARM7 BIOS - Optional | | | dsi_bios9.bin | DSi ARM9 BIOS - Optional | | | dsi_firmware.bin | DSi Firmware - Optional | | | dsi_nand.bin | DSi NAND - Optional | | | dsi_sd_card.bin | DSi SD Card - Optional | | ## Features Frontend-level settings or features that the melonDS core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The melonDS core's library name is 'melonDS' The melonDS core saves/loads to/from these directories. **Frontend's Cache directory** | File | Description | |:-----:|:----------------------:| | *.sav | Cartridge battery save | ### Geometry and timing - The melonDS core's core provided FPS is 59.8983059319 - The melonDS core's core provided sample rate is 32768 Hz - The melonDS core's base width is 256 - The melonDS core's base height is 384 - The melonDS core's max width is 256 - The melonDS core's max height is 384 - The melonDS core's core provided aspect ratio is 2/3 ## Controllers The melonDS core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. There's no reason to switch to this. - **Nintendo DS** - Joypad - Stay on this. ### Device tables #### Joypad ![](../image/controller/nds.png) | User 1 input descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Y | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | Up | ![](../image/retropad/retro_dpad_up.png) | | Down | ![](../image/retropad/retro_dpad_down.png) | | Left | ![](../image/retropad/retro_dpad_left.png) | | Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | X | ![](../image/retropad/retro_x.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | | Swap Screens | ![](../image/retropad/retro_r2.png) | | Close Lid | ![](../image/retropad/retro_l3.png) | ## Compatibility - [Upstream melonDS Forums Compatibility section](http://melonds.kuribo64.net/board/forum.php?id=3) ## External Links - [Official melonDS Website](http://melonds.kuribo64.net/) - [Official melonDS Github Repository](https://github.com/melonDS-emu/melonDS) - [Libretro melonDS Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/melonds_libretro.info) - [Libretro melonDS Github Repository](https://github.com/libretro/melonds) - [Report Libretro melonDS Core Issues Here](https://github.com/libretro/melonds/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0IfJciIgm46lbEVafdpVyyNA) ### See also #### Nintendo - Nintendo DS + Decrypted + (Download Play) - [Nintendo - DS (DeSmuME 2015)](desmume_2015.md) - [Nintendo - DS (DeSmuME)](desmume.md) - [Nintendo - DS (melonDS DS)](melonds_ds.md) ================================================ FILE: docs/library/melonds_ds.md ================================================ # Nintendo - DS (melonDS DS) ## Background A Nintendo DS emulator (with DSi support) by Arisotura and friends, ported to libretro by Jesse Talavera. !!! info "This is the newer version!" This version of the melonDS core is based on a newer version of the original emulator, and has more features than the older [melonDS core](melonds.md). Use this one unless you're not ready to migrate. ### Author/License The melonDS DS core has been authored by - Jesse Talavera The melonDS DS core is licensed under - [GPLv3](https://github.com/JesseTG/melonds-ds/blob/main/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the melonDS core has one of the following file extensions: - .nds - .dsi - .ids ## Databases RetroArch database(s) that are associated with the melonDS DS core: - [Nintendo - Nintendo DS](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%20DS.rdb) - [Nintendo - Nintendo DSi](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%20DSi.rdb) ## BIOS Required or optional firmware files go in the frontend's `system` directory. | Filename | Description | md5sum | |:----------------:|:------------------------------------:|:--------------------------------:| | bios7.bin | NDS ARM7 BIOS - Optional | df692a80a5b1bc90728bc3dfc76cd948 | | bios9.bin | NDS ARM9 BIOS - Optional | a392174eb3e572fed6447e956bde4b25 | | firmware.bin | NDS Firmware - Optional | Varies | | dsi_bios7.bin | DSi ARM7 BIOS - Required in DSi mode | | | dsi_bios9.bin | DSi ARM9 BIOS - Required in DSi mode | | | dsi_firmware.bin | DSi Firmware - Required in DSi mode | Varies | | dsi_nand.bin | DSi NAND - Required in DSi mode | Varies | ## Features Frontend-level settings or features that melonDS DS respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔[^1] | | Rewind | ✔[^1] | | Netplay | ✔[^2] | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✔ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✔ | | Sensors | ✔ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✔ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✔ | | Language | ✔ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The melonDS DS core's library name is 'melonDS DS' The melonDS DS core saves/loads to/from these directories. #### Frontend's Save directory | File | Description | |:--------------------:|:---------------------------:| | *.srm | Cartridge battery save | | dldi_sd_card.bin | Homebrew SD card image | | dldi_sd_card.bin.idx | Homebrew SD card file index | | dsi_sd_card.bin | DSi SD card image | | dsi_sd_card.bin.idx | DSi SD card file index | | *.public.sav | DSiWare public save data | | *.private.sav | DSiWare private save data | | *.banner.sav | DSiWare icon save data | #### Frontend's System directory | File | Description | |:--------------------:|:--------------------------------------:| | melonDS DS/tmd/*.tmd | DSiWare title ID file | | wfcsettings.bin | DS Wi-Fi settings (built-in BIOS only) | #### Frontend's State directory | File | Description | |:--------:|:-----------:| | *.state# | State | ### Geometry and timing - The melonDS DS core's core provided FPS is 59.898307800293 FPS. - The melonDS DS core's core provided sample rate is 32768 Hz. - The melonDS DS core's base width depends on the screen layout and configured renderer. - The melonDS DS core's base height depends on the screen layout and configured renderer. - The melonDS DS core's max width depends on the screen layout and configured renderer. - The melonDS DS core's max height depends on the screen layout and configured renderer. - The melonDS DS core's core-provided aspect ratio depends on the screen layout and configured renderer. ## Subsystems melonDS DS uses subsystems to enable inserting GBA ROMs into the emulated Slot-2. GBA save data (if any) must be loaded explicitly. Subsystems are not used for DSi mode. | Subsystem | Description | |:---------:|--------------------------------------------------------------| | gba | NDS ROM in Slot-1, GBA ROM in Slot-2 with optional save data | | gbanosav | NDS ROM in Slot-1, GBA ROM in Slot-2 with no GBA save data | !!! info "Not for playing GBA games." melonDS can load Game Boy Advance ROMs and save data for the purpose of Slot-2 connectivity, but it cannot actually play GBA games. Use a GBA core instead. Additional BIOS images are not required. ## Wi-Fi melonDS DS fully supports emulating Nintendo WFC services on all platforms. You can choose from one of several preconfigured servers in the core options menu, with [Kaeru WFC](https://kaeru.world/projects/wfc) being the default. If there's another server you'd like to use, you can set its DNS address from within the emulated console's Wi-Fi settings menu. !!! info "Not related to netplay!" Wi-fi emulation is not related to LAN-based netplay. ## LAN Netplay melonDS DS supports emulating LAN multiplayer via netplay. See below for instructions and details. ### What is LAN Multiplayer? The Nintendo DS has several forms of multiplayer, including local Wi-Fi (also called LAN), Nintendo Wi-Fi Connection (WFC) and infrared. You'll know when games use local Wi-Fi if the game mentions "Wi-Fi" and "players nearby", while games using WFC mention "players around the world" and use friend codes. The Nintendo DS local Wi-Fi does not use friend codes. This page only explains local Wi-Fi multiplayer. Now, the Nintendo DS local Wi-Fi isn't the normal Wi-Fi in your house, it is a [mesh network that uses specialized hardware](https://melonds.kuribo64.net/comments.php?id=25). This means that games expect extremely low latency, which is achievable between two consoles directly connected with special hardware, but harder to achieve with two computers with a router in-between, and simply **impossible** to achieve through the Internet. **LAN multiplayer does not work through the Internet and neither with VPNs or tunnels such as Hamachi**. This is not something that can be fixed easily. **The only way to use emulated LAN Multiplayer is on an actual, low latency, wired LAN connection**. The latency requirements are so extreme that even in LAN, you might still have issues. That is why using Wi-Fi in your LAN connection is not recommended, Wi-Fi simply adds too much latency, and the connection will drop frequently. The recommended way to use the emulated Wi-Fi LAN connection is with a wired LAN connection between the computers. ### What is a MAC address? Every Nintendo DS (and every device capable of Wi-Fi) comes with an identifier built-in in its firmware called a "MAC address". For three or more Nintendo DS consoles to connect in a local Wi-Fi multiplayer network, all three need to have different MAC addresses. You can see the emulated console's MAC address in a game with Nintendo WFC by going to "Nintendo WFC Settings", "Options", "System Information". Some games will refuse to load save files that were created on a console with a different MAC address than the console loading the file. That is why it is important to pay attention to your MAC address when sharing save files across devices. So how does the emulated console obtain a MAC address? It depends on the core option "MAC address mode", in the "Network" category: * Set from firmware: The default setting. The emulator will use the firmware file's MAC address for the emulated console. If there is no firmware file, then a default MAC address of "00-09-BF-11-22-33" will be used. This setting will cause issues on LAN multiplayer with more than 2 players if the same firmware (or the default firmware) is used on more than one device. * Derive from libretro username: The emulator will use your username as set on the libretro frontend to automatically generate a MAC address. Such generated MAC addresses will start with "00-08-BF". Devices with the same username set will always generate the same MAC address. Useful when syncing save files across devices to guarantee the emulated console's MAC address is the same on all devices. This setting will cause issues on LAN multiplayer if more than one player has the same username. The username can be set on RetroArch by going to "Settings", "User", "Username". ### Starting a multiplayer session (RetroArch) Before starting a multiplayer session, it is recommended that all set a proper username in "Settings", "User", "Username", in RetroArch, and set the MAC address mode to "Derive from libretro username". In RetroArch, such a multiplayer session can be started through the "Netplay" menu either before starting a game or during a game. One player should host and the others should use the "Refresh Netplay LAN List" option to join. In game, you'd look for something mentioning local multiplayer and "players nearby". In Pokémon games, this can be accessed on the top floor of Pokémon centers, in Mario Kart DS, it is the "Multiplayer" option in the menu etc. There are a ton of pages online saying that "Netplay is not network emulation". For various reasons, these pages are wrong when it comes to melonDS DS. Again, emulated LAN multiplayer only works if all players are on the same real local network. This means the same house, apartment etc. For better results, a wired connection is recommended. ## DSi melonDS DS supports DSi mode, which allows you to play DSi-enhanced games and DSiWare. **There is no need to prepare a NAND image externally;** when selecting a DSiWare game from RetroArch, it (and its previously-exported save data) will be temporarily installed on the configured NAND image. At the end of the session, the save data will be exported to the frontend's save directory and the DSiWare will be uninstalled. ## Screen Layouts melonDS DS supports a variety of screen layouts, including sideways rotation; you can configure a particular sequence of available layouts in the core options, and cycle through them with the `Next Screen Layout` button. Best used with per-game core option overrides. ## Controllers The melonDS DS core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. There's no reason to switch to this. - **Nintendo DS** - Joypad - Stay on this. Future device types may be added to include peripherals that provided additional inputs. ### Device tables #### Joypad ![](../image/controller/nds.png) | User 1 input descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Y | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | Up | ![](../image/retropad/retro_dpad_up.png) | | Down | ![](../image/retropad/retro_dpad_down.png) | | Left | ![](../image/retropad/retro_dpad_left.png) | | Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | X | ![](../image/retropad/retro_x.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | | Microphone | ![](../image/retropad/retro_l2.png) | | Next Screen Layout | ![](../image/retropad/retro_r2.png) | | Move Virtual Cursor | ![](../image/retropad/retro_right_stick.png) | | Close Lid | ![](../image/retropad/retro_l3.png) | | Touch Virtual Cursor | ![](../image/retropad/retro_r3.png) | ## Migrating from melonDS 2021 melonDS DS is intended to replace the [legacy melonDS core](melonds.md). If you have existing data you'd like to migrate, follow these steps. ### Save Files The save data format is unchanged between the legacy core and melonDS DS. However, the method used to save game data internally has changed. You'll need to do two things: 1. Go to the RetroArch save directory and rename the "melonDS" folder to "melonDS DS" (if it exists) 2. Rename the save files from `.sav` to `.srm`. ### Savestates **Savestates taken in the legacy core cannot be migrated to melonDS DS.** In the time since the last release of the legacy core, the savestate format has changed upstream. _Save your game normally before migrating your data to melonDS DS._ ### Config Files Rename the following directories to `melonDS DS`: - `$RETROARCH_ROOT/config/melonDS` to `melonDS DS`. - `$RETROARCH_ROOT/config/remaps/melonDS` to `melonDS DS`. - Rename any files inside these directories named `melonDS.opt` to `melonDS DS.opt`. ### Cheats Rename `$RETROARCH_ROOT/cheats/melonDS` to `melonDS DS`. Cheat support is unchanged. ### System Files melonDS DS will detect system files (BIOS, firmware, NAND) in the system directory, so no action is required from you. However, melonDS DS will prefer system files in the "melonDS DS" subdirectory. ## Compatibility - [Upstream melonDS Forums Compatibility section](http://melonds.kuribo64.net/board/forum.php?id=3) ## External Links - [Official melonDS Website](http://melonds.kuribo64.net/) - [Official melonDS GitHub Repository](https://github.com/melonDS-emu/melonDS) - [Libretro melonDS DS Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/melondsds_libretro.info) - [Libretro melonDS DS Github Repository](https://github.com/JesseTG/melonds-ds) - [Report Libretro melonDS DS Core Issues Here](https://github.com/JesseTG/melonds-ds/issues) ### See also #### Nintendo - Nintendo DS + Decrypted + (Download Play) - [Nintendo - DS (DeSmuME 2015)](desmume_2015.md) - [Nintendo - DS (DeSmuME)](desmume.md) - [Nintendo - DS (melonDS 2021)](melonds.md) [^1]: Not available in DSi mode. [^2]: LAN only. (No, VPNs won't work.) ================================================ FILE: docs/library/mesen-s.md ================================================ # Nintendo - SNES / SFC / Game Boy / Color (Mesen-S) ## Background Mesen-S is a cross-platform SNES emulator for Windows & Linux built in C++ and C#. Features - High Accuracy: A lot of effort has gone into making Mesen-S as accurate as possible. - High Compatibility - SNES, Super Famicom, Game Boy, and Game Boy Color emulation is supported. Super Game Boy has complete support. ### Author/License The Mesen-S core has been authored by - M. Bibaud (aka Sour) The Mesen-S core is licensed under - [GPLv3](https://github.com/SourMesen/Mesen-S/blob/master/README.md) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:-----------------:|:--------------------------------------:|:--------------------------------:| | dsp1.data.rom | DSP1 co-processor firmware - Optional | 3d81b45fa0c2aa8b852dfb1ece7c0971 | | dsp1.program.rom | DSP1 co-processor firmware - Optional | ae209fbe789fbf11a48aea5ab1197321 | | dsp1b.data.rom | DSP1B co-processor firmware - Optional | 1e3f568634a7d8284020dddc0ae905bc | | dsp1b.program.rom | DSP1B co-processor firmware - Optional | d10f446888e097cbf500f3f663cf4f6d | | dsp2.data.rom | DSP2 co-processor firmware - Optional | e9417e29223b139c3c4b635a2a3b8744 | | dsp2.program.rom | DSP2 co-processor firmware - Optional | aa6e5922a3ed5ded54f24247c11143c5 | | dsp3.data.rom | DSP3 co-processor firmware - Optional | 0a81210c0a940b997dd9843281008ee6 | | dsp3.program.rom | DSP3 co-processor firmware - Optional | d99ca4562818d49cee1f242705bba6f8 | | dsp4.data.rom | DSP4 co-processor firmware - Optional | ee4990879eb68e3cbca239c5bc20303d | | dsp4.program.rom | DSP4 co-processor firmware - Optional | a151023b948b90ffc23a5b594bb6fef2 | | st010.data.rom | ST010 co-processor firmware - Optional | 254d70762b6f59f99c27c395aba7d07d | | st010.program.rom | ST010 co-processor firmware - Optional | 1d70019179a59a566a0bb5d3f2845544 | | st011.data.rom | ST011 co-processor firmware - Optional | 10bd3f4aa949737ab9836512c35bcc29 | | st011.program.rom | ST011 co-processor firmware - Optional | 95222ebf1c0c2990bcf25db43743f032 | | dmg_boot.bin | GB Boot Image - Optional | 32fbbd84168d3482956eb3c5051637f5 | | cgb_boot.bin | GBC Boot Image - Optional | dbfce9db9deaa2567f6a84fde55f9680 | | sgb_boot.bin | SGB Boot Image - Optional | d574d4f9c12f305074798f54c091a8b4 | | sgb2_boot.bin | SGB2 Boot Image - Optional | e0430bca9925fb9882148fd2dc2418c1 | | SGB1.sfc | SGB ROM - Optional | b15ddb15721c657d82c5bab6db982ee9 | | SGB2.sfc | SGB2 ROM - Optional | 8ecd73eb4edf7ed7e81aef1be80031d5 | | BS-X.bin | Satellaview Boot ROM - Optional | fed4d8242cfbed61343d53d48432aced | ## Extensions Content that can be loaded by the Mesen-S core have the following file extensions: - .sfc - .smc - .fig - .swc - .bs - .gb - .gbc ## Databases RetroArch database(s) that are associated with the Mesen-S core: - [Nintendo - Game Boy](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Game%20Boy.rdb) - [Nintendo - Game Boy Color](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Game%20Boy%20Color.rdb) - [Nintendo - Super Nintendo Entertainment System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System.rdb) - [Nintendo - Satellaview](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Satellaview.rdb) ## Features Frontend-level settings or features that the Mesen-S core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✔ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✔ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✔ | | LEDs | ✕ | ## Directories The Mesen-S core's library name is 'Mesen-S' The Mesen-S core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:----------------------:| | *.srm | Cartridge battery save | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ## Geometry and timing - The Mesen-S core's core provided FPS is 60 for NTSC games and 50 for PAL games. - The Mesen-S core's core provided sample rate is 32040 Hz - The Mesen-S core's base width is 256 - The Mesen-S core's base height is 239 - The Mesen-S core's max width is 512 - The Mesen-S core's max height is 478 - The Mesen-S core's core provided aspect ratio is dependent on the ['Aspect Ratio' core option](#core-options) ## Core options The Mesen-S core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. !!! attention These core option descriptions have been sourced from the [official Mesen-S documentation](https://www.mesen.ca/snes/docs/). Please go there for more information. - **NTSC filter** [mesen-s_ntsc_filter] (**Disabled**/Composite (Blargg)/S-Video (Blargg)/RGB (Blargg)/Monochrome (Blargg)) Selects a filter to apply to the picture. The NTSC filter available in Mesen-S is blargg’s NTSC filter - this filter is very fast, and available in various other emulators. - **Region** [mesen-s_region] (**Auto**/NTSC/PAL) When set to Auto, the emulator will try to detect the game’s region (NTSC or PAL) - however, this is not always possible. When there is nothing to suggest a game is for the PAL region (Australia & Europe), the NTSC region (North America & Japan) will be used by default. - **Game Boy Model** [mesen-s_gbmodel] (**Auto**/Game Boy/Game Boy Color/Super Game Boy) Determines which Game Boy model to emulate when loading a Game Boy or Game Boy Color game. When Auto is selected, Super Game Boy emulation is used for Game Boy games, and Game Boy Color emulation is used for Game Boy Color games. - **Use SGB2** [mesen-s_sgb2] (Off/**On**) When enabled, Super Game Boy 2 is used when emulating the SGB. Super Game Boy 2 has corrected CPU timing and some slight differences in behavior. - **Vertical Overscan** [mesen-s_overscan_vertical] (**None**/8px/16px) This overscan setting allow you to cut out pixels vertically on the edge of the screen. On a CRT TV, a few pixels on each side of the screen are usually hidden. Most SNES games output 224 scanlines, while others use the SNES’ 239 scanlines mode. To avoid the window or picture size changing when the game changes between either mode, Mesen-S always outputs 239 scanlines. In the vast majority of games, this results in 7 blank lines on the top and 8 on the bottom. To hide these blank scanlines, set the overscan value to 8. - **Horizontal Overscan** [mesen-s_overscan_horizontal] (**None**/8px/16px) This overscan setting allow you to cut out pixels horizontally on the edge of the screen. - **Aspect Ratio** [mesen-s_aspect_ratio] (**Auto**/No Stretching/NTSC/PAL/4:3/16:9) The SNES’ resolution in most games is 256x224, but it used to be displayed on CRT TVs that had a rectangular picture. To simulate a CRT TV, you can use the Auto option - it will switch between NTSC and PAL aspect ratios depending on the game you are playing. Using anything other than the Default (No Stretching) option may cause pixels to have irregular sizes. You can reduce this effect by using video filters. - **Blend Hi-Res Modes** [mesen-s_blend_high_res] (**Off**/On) Some games use the SNES’ “high resolution” mode which produces a 512x224 picture. However, this mode causes horizontal blending, which is sometimes used for pseudo-transparency effects. Enabling this option will allow these pseudo-transparency effects to look as they were intended (but causes the entire picture to look softer/blurrier). - **Cubic Interpolation (Audio)** [mesen-s_cubic_interpolation] (**Off**/On) This option replaces the SNES’ default gaussian interpolation filter with a cubic interpolation filter which can produce better audio. - **Overclock** [mesen-s_overclock] (**None**/Low/Medium/High/Very High) Use this to overclock the CPU. !!! warning Overclocking can cause issues in some games. - **Overclock Type** [mesen-s_overclock_type] (**Before NMI**/After NMI) Before NMI: Increases the number of scanlines in the PPU, *before* the NMI signal is triggered at the end of the visible frame. This effectively gives more time for games to perform calculations, which can reduce slowdowns in games. **This is the preferred option for overclocking.** After NMI: Increases the number of scanlines in the PPU, *after* the NMI signal is triggered at the end of the visible frame. This effectively gives more time for games to perform calculations, which can reduce slowdowns in games. **This option is less compatible and should only be used if the *Before NMI* variation does not work as expected.** - **Super FX Clock Speed** [mesen-s_superfx_overclock] (**100%**/200%/300%/400%/500%/1000%) Increases the clock speed used for the Super FX chip, which can reduce lag in Super FX games. This method of overclocking is more efficient for Super FX titles. - **Default power-on state for RAM** [mesen-s_ramstate] (**Random Values (Default)**/All 0s/All 1s) On a console, the RAM’s state at power on is undetermined and relatively random. This option lets you select Mesen-S’ behavior when initializing RAM - set all bits to 0, set all bits to 1, or randomize the value of each bit. ## Controllers The Mesen-S core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Input disabled. - **RetroPad** - Joypad - [SNES Controller](https://nintendo.fandom.com/wiki/Super_Nintendo_Entertainment_System_controller) - Joypad - [SNES Mouse](https://nintendo.fandom.com/wiki/SNES_Mouse) - Mouse ### User 2 device types - None - Input disabled. - **RetroPad** - Joypad - SNES Controller - [SNES Controller](https://nintendo.fandom.com/wiki/Super_Nintendo_Entertainment_System_controller) - Joypad - [SNES Mouse](https://nintendo.fandom.com/wiki/SNES_Mouse) - Mouse - [Super Scope](https://nintendo.fandom.com/wiki/Super_Scope) - Lightgun - [Multitap](https://nintendo.fandom.com/wiki/Super_Multitap) - Joypad - Allows for up to five players to play together in mulitap games. ### User 3 - 5 device types - None - Input disabled. - **RetroPad** - Joypad - [SNES Controller](https://nintendo.fandom.com/wiki/Super_Nintendo_Entertainment_System_controller) - Joypad ### Multitap Multitap support can be activated in the Mesen-S core by switching User 2's device type to Multitap. ### Controller tables #### Joypad | User Remap descriptors for 'SNES Controller' device type | RetroPad Inputs | |----------------------------------------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Y | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | X | ![](../image/retropad/retro_x.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | #### Mouse | RetroMouse Inputs | SNES Mouse | |-------------------------------------------------------|-------------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | SNES Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | SNES Mouse Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | SNES Mouse Right Button | #### Pointer | RetroPointer Inputs | Super Scope | |--------------------------------------------------------------------------------------------------------------------------|---------------| | ![](../image/retromouse/retro_mouse.png) or ![](../image/Button_Pack/Gestures/Gesture_Finger_Front.png) Pointer Position | Crosshair | | ![](../image/retromouse/retro_left.png) Mouse 1 | Fire | | ![](../image/retromouse/retro_right.png) Mouse 2 | Cursor Button | | ![](../image/retromouse/retro_middle.png) Mouse 3 | Turbo Toggle | !!! attention Currently there is no crosshair. Pressing the mouse grab binding twice in RetroArch (default F11) should make your system cursor visible. ## Compatibility The Mesen-S core fully emulates all SNES, GB, and GBC games that have ever been officially released. ## External Links - [Official Mesen-S Website](https://www.mesen.ca/) - [Official Mesen-S Documentation](https://www.mesen.ca/snes/docs/) - [Libretro Mesen-S Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mesen-s_libretro.info) - [Official Mesen-S Github Repository](https://github.com/SourMesen/Mesen-S) - [Report Libretro Mesen-S Core Issues Here](https://github.com/SourMesen/Mesen-S/issues) ### See also #### Nintendo - Game Boy (+ Color) - [Nintendo - Game Boy / Color (Emux GB)](emux_gb.md) - [Nintendo - Game Boy / Color (Gambatte)](gambatte.md) - [Nintendo - Game Boy / Color (Gearboy)](gearboy.md) - [Nintendo - Game Boy / Color (SameBoy)](sameboy.md) - [Nintendo - Game Boy / Color (TGB Dual)](tgb_dual.md) - [Nintendo - Game Boy Advance (mGBA)](mgba.md) - [Nintendo - Game Boy Advance (VBA-M)](vba_m.md) - [Nintendo - SNES / Famicom (bsnes-jg)](bsnes-jg.md) - [Nintendo - SNES / Famicom (higan Accuracy)](higan_accuracy.md) - [Nintendo - SNES / Famicom (nSide Balanced)](nside_balanced.md) #### SNES - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-jg)](bsnes-jg.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (higan Accuracy)](higan_accuracy.md) - [Nintendo - SNES / Famicom (nSide Balanced)](nside_balanced.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) ================================================ FILE: docs/library/mesen.md ================================================ # Nintendo - NES / Famicom (Mesen) ## Background Mesen is a high-accuracy NES and Famicom emulator and NSF player for Windows and Linux. Features - High Accuracy: A lot of effort has gone into making Mesen as accurate as possible. - High Compatibility: Over 220 mappers supported (all licensed games supported) - NES, Famicom, Famicom Disk System, Dendy, VS System, NSF and NSFe emulation is supported. - General: Save States, Rewinding, Movie/Audio Recording, Overclocking, Cheat Codes. - Video: Numerous video filters, customizable palettes/overscan, support for HDNes' HD packs. - Audio: Stereo effects, per-channel volume and panning, equalizer, etc. - Misc: Netplay, 7z/zip support, IPS/BPS patch support, automatic updates, and more! ### Author/License The Mesen core has been authored by - M. Bibaud (aka Sour) The Mesen core is licensed under - [GPLv3](https://github.com/SourMesen/Mesen/blob/master/README.md) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Mesen core have the following file extensions: - .nes - .fds - .unf - .unif ## Databases RetroArch database(s) that are associated with the Mesen core: - [Nintendo - Nintendo Entertainment System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%20Entertainment%20System.rdb) - [Nintendo - Family Computer Disk System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Family%20Computer%20Disk%20System.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:-----------:|:-------------------------------------------------------------------------------------:|:--------------------------------:| | disksys.rom | Family Computer Disk System BIOS - Required for Family Computer Disk System emulation | ca30b50f880eb660a320674ed365ef7a | ## Features Frontend-level settings or features that the Mesen core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Mesen core's library name is 'Mesen' The Mesen core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:----------------------:| | *.srm | Cartridge battery save | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | **Frontend's System directory** | File | Description | |:-----------------:|:-----------------:| | MesenPalette.pal | Custom palette | | HdPacks/* | HD Pack directory | ### Geometry and timing - The Mesen core's core provided FPS is NTSC 60, PAL/Dendy 50 - The Mesen core's core provided sample rate is 48000 Hz - The Mesen core's base width is 256 - The Mesen core's base height is 240 - The Mesen core's max width is 256 (higher when using HD Packs) - The Mesen core's max height is 240 (higher when using HD Packs) - The Mesen core's core provided aspect ratio is dependent on the ['Aspect Ratio' core option](#core-options). ### Custom Palettes To use custom color palettes in the Mesen core, the ['Palette' core option](#core-options) must be set to Custom and the custom color palette file you want to use must be in RetroArch's system directory. Make sure the custom palette file is named 'MesenPalette.pal' Custom color palettes for the NES can be generated with either of these tools. - [Bisqwit's NTSC NES palette generator](http://bisqwit.iki.fi/utils/nespalette.php) - [Drag's NTSC NES palette generator](http://drag.wootest.net/misc/palgen.html) ## HD packs !!! attention There is more HD pack documentation at the [official Mesen documentation](https://www.mesen.ca/docs/hdpacks/#using-hd-packs). To use HD packs, first make sure to turn on the [Enable HD Packs core option](#core-options.) First, create a folder named 'HdPacks' in RetroArch's System directory. Next, create a folder inside the HdPacks directory that has the same name as the content you're going to load. So, if the content you're loading is Mega Man (USA).nes, the folder should be named 'Mega Man (USA)'. Finally, extract the HD pack content files to the Mega Man (USA) folder. Here's an example of a working HD pack setup done with [Mega Man 1 (NES) - 30th Anniversary 16-bit Graphic Pack](https://www.romhacking.net/forum/index.php?topic=25426.0). Pay attention to the file path. ![](../image/core/mesen/hdpack.png) ## Core options The Mesen core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. !!! attention These core option descriptions have been sourced from the [official Mesen documentation](https://www.mesen.ca/docs/). Please go there for more information. - **NTSC filter** [mesen_ntsc_filter] (**Disabled**/Composite (Blargg)/S-Video (Blargg)/RGB (Blargg)/Monochrome (Blargg)/Bisqwit 2x/Bisqwit 4x/Bisqwit 8x) Selects a filter to apply to the picture. Blargg filters are fast. Bisqwit filters are slower. - **Palette** [mesen_palette] (**Default**/Composite Direct (by FirebrandX)/Nes Classic/Nestopia (RGB)/Original Hardware (by FirebrandX)/PVM Style (by FirebrandX)/Sony CXA2025AS/Unsaturated v6 (by FirebrandX)/YUV v3 (by FirebrandX)/Custom) Mesen comes with a number of built-in palette options - you can select them from here. - **Overclock** [mesen_overclock] (**None**/Low/Medium/High/Very High) Use this to overclock or underclock the CPU. !!! warning Overclocking can cause issues in some games. - **Overclock Type** [mesen_overclock_type] (**Before NMI (Recommended)**/After NMI) Before NMI: Increases the number of scanlines in the PPU, before the NMI signal is triggered at the end of the visible frame. This effectively gives more time for games to perform calculations, which can reduce slowdowns in games. **This is the preferred option for overclocking.** After NMI: Increases the number of scanlines in the PPU, after the NMI signal is triggered at the end of the visible frame. This effectively gives more time for games to perform calculations, which can reduce slowdowns in games. **This option is less compatible and should only be used if the before NMI variation does not work as expected.** - **Region** [mesen_region] (**Auto**/NTSC/PAL/Dendy) When set to Auto, the emulator will try to detect the game’s region (NTSC or PAL) - however, this is not always possible. When there is nothing to suggest a game is for the PAL region (Australia & Europe), the NTSC region (North America & Japan) will be used by default. Dendy is used to mimic a number of different NES clones, in particular, the Dendy, which was a popular clone in Russia. - **Vertical Overscan** [mesen_overscan_vertical] (**None**/8px/16px) This overscan setting allow you to cut out pixels vertically on any edge of the screen. On a CRT TV, a few pixels on each side of the screen was usually invisible to the player. Because of this, games often have glitches or incorrect palette colors on the edges of the screen – this is normal and caused by the game itself. Setting a value of 8 or so on each side of the overscan configuration will usually hide most glitches. - **Horizontal Overscan** [mesen_overscan_horizontal] (**None**/8px/16px) This overscan setting allow you to cut out pixels horizontally on any edge of the screen. On a CRT TV, a few pixels on each side of the screen was usually invisible to the player. Because of this, games often have glitches or incorrect palette colors on the edges of the screen – this is normal and caused by the game itself. Setting a value of 8 or so on each side of the overscan configuration will usually hide most glitches. - **Aspect Ratio** [mesen_aspect_ratio] (**Auto**/No Stretching/NTSC/PAL/4:3/16:9) The NES’ internal aspect ratio is almost square (Default (No Stretching)), but it used to be displayed on CRT TVs that had a rectangular picture. To simulate a CRT TV, you can use the Auto option - it will switch between NTSC and PAL aspect ratios depending on the game you are playing. Using anything other than the Default (No Stretching) option may cause pixels to have irregular sizes. You can reduce this effect by using a combination of video filters and the bilinear filtering option. - **Controller Turbo Speed** [mesen_controllerturbospeed] (**Fast**/Very Fast/Disabled/Slow/Normal) Configure the controller's turbo buttons' speed. - **Enable HD Packs** [mesen_hdpacks] (Off/**On**) Enables the use of [HD packs](https://www.mesen.ca/docs/hdpacks/). [Look at the HD packs section for more information](#hd-packs). - **Remove sprite limit** [mesen_nospritelimit] (Off/**On**) The NES can normally only draw up to 8 sprites per line – this limitation is indirectly responsible for some of the flickering seen in games at times. When this option is enabled, the limit is disabled, allowing up to 64 sprites to be drawn on the same line. - **Enable fake stereo effect** [mesen_fake_stereo] (**Off**/On) Self-explanatory. - **Reduce popping on Triangle channel** [mesen_mute_triangle_ultrasonic] (Off/**On**) This option mutes the triangle channel under certain conditions, which prevents it from causing popping sounds. - **Reduce popping on DMC channel** [mesen_reduce_dmc_popping] (Off/**On**) Similar to the previous option, but for the DMC channel – this option prevents games from changing the output of the DMC channel too abruptly, which often causes popping sounds. - **Swap Square channel duty cycles** [mesen_swap_duty_cycle] (**Off**/On) This option is to mimic some older NES clones that had incorrect sound output for both of the square channels. It greatly alters the sound in some games, and shouldn’t be enabled unless you want this behavior. - **Disable Noise channel mode flag** [mesen_disable_noise_mode_flag] (**Off**/On) Very early Famicom models did not implement this feature, so this option is available to mimic early Famicom consoles. It changes the sound output of the noise channel in some games, and shouldn’t be enabled unless you want this behavior. - **Screen Rotation** [mesen_screenrotation] (**None**/90 degrees/180 degrees/270 degrees) Rotates the display by the specified angle. This is useful to play games (generally homebrew games) designed for a vertical display. - **Default power-on state for RAM** [mesen_ramstate] (**All 0s (Default)**/All 1s/Random Values) On a console, the RAM’s state at power on is undetermined and relatively random. This option lets you select Mesen’s behavior when initializing RAM - set all bits to 0, set all bits to 1, or randomize the value of each bit. - **FDS: Automatically insert disks** [mesen_fdsautoinsertdisk] (**Off**/On) By default, the FDS boots with no disk inserted in the drive. This option makes it so the player does not need to manually insert disk 1, side A manually. - **FDS: Fast forward while loading** [mesen_fdsfastforwardload] (**Off**/On) FDS games contain a large number of load screens due to their data being stored on floppy drives. Mesen needs to emulate this floppy drive’s speed to ensure accurate emulation. This option makes it so Mesen runs the emulation as fast as it can when a game is loading data from the disk, which greatly reduces the time spent on loading screens. ## Controllers The Mesen core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 - 2 device types - None - Input disabled. - **Auto** - Joypad - Automatically selects an input device according to the data in the game database. - [Standard Controller](https://wiki.nesdev.com/w/index.php/Standard_controller) - Joypad - Manually selects a standard game controller. - [Zapper](https://wiki.nesdev.com/w/index.php/Zapper) - Pointer - Manually selects a Zapper light gun. - [Power Pad](https://wiki.nesdev.com/w/index.php/Power_Pad) - Joypad - Manually selects a Power Pad peripheral. - [Arkanoid](https://wiki.nesdev.com/w/index.php/Arkanoid_controller) - Mouse - Manually selects an Arkanoid controller. - [SNES Controller](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller) - Joypad - Manually selects a SNES Controller. - [SNES Mouse](https://wiki.nesdev.com/w/index.php/Mouse) - Mouse - Manually selects a SNES Mouse. ### User 3 device types - None - Input disabled. - **Auto** - Joypad - Automatically selects an input device according to the data in the game database. - [Standard Controller](https://wiki.nesdev.com/w/index.php/Standard_controller) - Joypad - Manually selects a standard game controller. ### User 4 device types - None - Input disabled. - **Auto** - Joypad - Automatically selects an input device according to the data in the game database. - [Standard Controller](https://wiki.nesdev.com/w/index.php/Standard_controller) - Joypad - Manually selects a standard game controller. ### User 5 device types - None - Input disabled. - **Auto** - Joypad - Automatically selects an input device according to the data in the game database. - [Arkanoid](https://wiki.nesdev.com/w/index.php/Arkanoid_controller) - Mouse - Manually selects an Arkanoid controller. - [Ascii Turbo Fire](https://en.wikipedia.org/wiki/Turbo_File_(ASCII)) - None - Manually selects an Ascii Turbo Fire device. - Bandai Hypershot - Pointer - Manually selects a Bandai Hypershot light gun. - Battle Box - None - Manually selects a Battle Box device. - [Exciting Boxing](https://wiki.nesdev.com/w/index.php/Exciting_Boxing_Punching_Bag) - Joypad - Manually selects an Exciting Boxing punching bag. - [Family Trainer](https://wiki.nesdev.com/w/index.php/Power_Pad) - Joypad - Manually selects a Family Trainer peripheral. - [Four Player Adapter](https://wiki.nesdev.com/w/index.php/Four_Score) - None - Manually selects a Four Player Adapter device. - [Hori Track](https://wiki.nesdev.com/w/index.php/Mouse#Hori_Track) - Mouse - Manually selects a Hori Track trackball. - [Konami Hypershot](https://wiki.nesdev.com/w/index.php/Konami_Hyper_Shot) - Joypad - Manually selects a Konami Hypershot controller. - [Pachinko](https://wiki.nesdev.com/w/index.php/Coconuts_Pachinko) - Joypad - Manually selects a Pachinko controller. - [Partytap](https://wiki.nesdev.com/w/index.php/Partytap) - Joypad - Manually selects Partytap controllers. ### Other controllers - [Oeka Kids Tablet](https://wiki.nesdev.com/w/index.php/Oeka_Kids_tablet) - Pointer - The Mesen core will automatically select the Oeka Kids Tablet input device according to the data in the game database. It cannot be manually selected as a device type in RetroArch's controls menu. ### Multitap support Multitap support can be activated in the Mesen core by switching User 5's device type to Four Player Adapter. ### Controller tables #### Joypad !!! attention The (FDS) Insert Next Disk and (FDS) Switch Disk Side inputs will NOT do anything while the ['FDS: Automatically insert disks' core option](#core-options) is enabled. ![](../image/controller/nes.png) | User Remap descriptors for 'Standard Controller' device type | RetroPad Inputs | |--------------------------------------------------------------|---------------------------------------------| | A | ![](../image/retropad/retro_b.png) | | B | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | Turbo A | ![](../image/retropad/retro_a.png) | | Turbo B | ![](../image/retropad/retro_x.png) | | (FDS) Insert Next Disk | ![](../image/retropad/retro_l1.png) | | (FDS) Switch Disk Side | ![](../image/retropad/retro_r1.png) | | (VS) Insert Coin 1 | ![](../image/retropad/retro_l2.png) | | (VS) Insert Coin 2 | ![](../image/retropad/retro_r2.png) | | (Famicom) Microphone | ![](../image/retropad/retro_l3.png) | | User Remap descriptors for 'SNES Controller' device type | RetroPad Inputs | |----------------------------------------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Y | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | X | ![](../image/retropad/retro_x.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | | User Remap descriptors for 'Power Pad' and 'Family Trainer' device types | RetroPad Inputs | |--------------------------------------------------------------------------|---------------------------------------------| | Powerpad B1 | ![](../image/retropad/retro_b.png) | | Powerpad B3 | ![](../image/retropad/retro_y.png) | | Powerpad B11 | ![](../image/retropad/retro_select.png) | | Powerpad B12 | ![](../image/retropad/retro_start.png) | | Powerpad B9 | ![](../image/retropad/retro_dpad_up.png) | | Powerpad B10 | ![](../image/retropad/retro_dpad_down.png) | | Powerpad B7 | ![](../image/retropad/retro_dpad_left.png) | | Powerpad B8 | ![](../image/retropad/retro_dpad_right.png) | | Powerpad B2 | ![](../image/retropad/retro_a.png) | | Powerpad B4 | ![](../image/retropad/retro_x.png) | | Powerpad B5 | ![](../image/retropad/retro_l1.png) | | Powerpad B6 | ![](../image/retropad/retro_r1.png) | | User Remap descriptors for 'Exciting Boxing' device type | RetroPad Inputs | |----------------------------------------------------------|---------------------------------------------| | Left Hook | ![](../image/retropad/retro_b.png) | | Left Jab | ![](../image/retropad/retro_y.png) | | Move Left | ![](../image/retropad/retro_dpad_left.png) | | Move Right | ![](../image/retropad/retro_dpad_right.png) | | Right Hook | ![](../image/retropad/retro_a.png) | | Right Jab | ![](../image/retropad/retro_x.png) | | Body | ![](../image/retropad/retro_l1.png) | | Straight | ![](../image/retropad/retro_r1.png) | | User Remap descriptors for 'Pachinko' device type | RetroPad Inputs | |---------------------------------------------------|-------------------------------------| | Release Trigger | ![](../image/retropad/retro_l1.png) | | Press Trigger | ![](../image/retropad/retro_r1.png) | | User Remap descriptors for 'Partytap' device type | RetroPad Inputs | |---------------------------------------------------|-------------------------------------| | Partytap P1 | ![](../image/retropad/retro_b.png) | | Partytap P3 | ![](../image/retropad/retro_y.png) | | Partytap P2 | ![](../image/retropad/retro_a.png) | | Partytap P4 | ![](../image/retropad/retro_x.png) | | Partytap P5 | ![](../image/retropad/retro_l1.png) | | Partytap P6 | ![](../image/retropad/retro_r1.png) | | RetroPad Inputs | Konami Hypershot | |------------------------------------------------|------------------| | ![](../image/retropad/retro_b.png) | Jump | | ![](../image/retropad/retro_y.png) | Run | | ![](../image/retropad/retro_a.png) | Turbo Jump | | ![](../image/retropad/retro_x.png) | Turbo Run | #### Mouse | RetroMouse Inputs | Arkanoid | SNES Mouse | Hori Track | |-------------------------------------------------------|-------------------|-------------------------|-------------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Arkanoid Movement | SNES Mouse Cursor | Hori Track Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | Arkanoid Fire | SNES Mouse Left Button | Hori Track Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | | SNES Mouse Right Button | Hori Track Right Button | #### Pointer | RetroPointer Inputs | Zapper | Bandai Hypershot | Oeka Kids Tablet | |--------------------------------------------------------------------------------------------------------------------------|------------------|----------------------------|------------------------------| | ![](../image/retromouse/retro_mouse.png) or ![](../image/Button_Pack/Gestures/Gesture_Finger_Front.png) Pointer Position | Zapper Crosshair | Bandai Hypershot Crosshair | Oeka Kids Tablet Stylus | | ![](../image/retromouse/retro_left.png) Mouse 1 | Zapper Fire | Bandai Hypershot Fire | Oeka Kids Tablet Click/Touch | | ![](../image/retromouse/retro_right.png) Mouse 2 | Zapper Offscreen | Bandai Hypershot Offscreen | | ## Compatibility - [Mesen Mapper Support List](https://github.com/SourMesen/Mesen/blob/master/Core/MapperFactory.cpp#L275) ## External Links - [Official Mesen Website](https://www.mesen.ca/) - [Official Mesen Documentation](https://www.mesen.ca/docs/) - [Official Mesen Downloads](https://www.mesen.ca/#Downloads) - [Official Mesen Changelog](https://www.mesen.ca/#Changelog) - [Libretro Mesen Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mesen_libretro.info) - [Official Mesen Github Repository](https://github.com/SourMesen/Mesen) - [Report Libretro Mesen Core Issues Here](https://github.com/SourMesen/Mesen/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0IdbTgE4bID9L5s5f323IewO) ### See also #### Nintendo - Family Computer Disk System - [Nintendo - NES / Famicom (FCEUmm)](fceumm.md) - [Nintendo - NES / Famicom (Nestopia)](nestopia.md) #### Nintendo - Nintendo Entertainment System - [Nintendo - NES / Famicom (bnes)](bnes.md) - [Nintendo - NES / Famicom (Emux NES)](emux_nes.md) - [Nintendo - NES / Famicom (FCEUmm)](fceumm.md) - [Nintendo - NES / Famicom (Nestopia)](nestopia.md) - [Nintendo - NES / Famicom (QuickNES)](quicknes.md) ================================================ FILE: docs/library/meteor.md ================================================ # Nintendo - Game Boy Advance (Meteor) ## Background Meteor is a Gameboy Advance emulator. The Meteor core has been authored by - Philippe Daouadi The Meteor core is licensed under - [GPLv3](https://github.com/libretro/meteor-libretro/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Meteor core have the following file extensions: - .gba ## Databases RetroArch database(s) that are associated with the Meteor core: - [Nintendo - Game Boy Advance](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Game%20Boy%20Advance.rdb) ## Features Frontend-level settings or features that the Meteor core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Meteor core's internal core name is 'Meteor GBA' The Meteor core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.srm (Cartridge battery save) **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The Meteor core's core provided FPS is 59.7275005696 - The Meteor core's core provided sample rate is 44100 Hz - The Meteor core's core provided aspect ratio is 3/2 ## Controllers The Meteor core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. There's no reason to switch to this. - **RetroPad** - Joypad - Stay on this. - RetroPad w/Analog - Joypad - Same as RetroPad. There's no reason to switch to this. ### Controller tables #### Joypad ![](../image/controller/gba.png) | User 1 Remap descriptors | RetroPad Inputs | |--------------------------|-------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | ## Compatibility Awaiting description. ## External Links - [Official Meteor Github Repository](https://github.com/blastrock/meteor) - [Libretro Meteor Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/meteor_libretro.info) - [Libretro Meteor Github Repository](https://github.com/libretro/meteor-libretro) - [Report Libretro Meteor Core Issues Here](https://github.com/libretro/meteor-libretro/issues) ### See also #### Nintendo - Game Boy Advance - [Nintendo - Game Boy Advance (Beetle GBA)](beetle_gba.md) - [Nintendo - Game Boy Advance (gpSP)](gpsp.md) - [Nintendo - Game Boy Advance (mGBA)](mgba.md) - [Nintendo - Game Boy Advance (TempGBA)](tempgba.md) - [Nintendo - Game Boy Advance (VBA-M)](vba_m.md) - [Nintendo - Game Boy Advance (VBA Next)](vba_next.md) ================================================ FILE: docs/library/mgba.md ================================================ # Nintendo - Game Boy Advance (mGBA) ## Background mGBA is an emulator for running Game Boy Advance games. It aims to be faster and more accurate than many existing Game Boy Advance emulators, as well as adding features that other emulators lack. It also supports Game Boy and Game Boy Color games. The mGBA core has been authored by - endrift The mGBA core is licensed under - [MPLv2.0](https://github.com/libretro/mgba/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Required or optional firmware files go in the frontend's system directory. !!! warning In order for the BIOS to be used, the 'Use BIOS file if found' core option must be set to On. | Filename | Description | md5sum | |:------------:|:--------------------------------:|:--------------------------------:| | gba_bios.bin | Game Boy Advance BIOS - Optional | a860e8c0b6d573d191e4ec7db1b1e4f6 | | gb_bios.bin | Game Boy BIOS - Optional | 32fbbd84168d3482956eb3c5051637f5 | | gbc_bios.bin | Game Boy Color BIOS - Optional | dbfce9db9deaa2567f6a84fde55f9680 | | sgb_bios.bin | Super Game Boy BIOS - Optional | d574d4f9c12f305074798f54c091a8b4 | ## Extensions Content that can be loaded by the mGBA core have the following file extensions: - .gb - .gbc - .gba RetroArch database(s) that are associated with the [Core name] core: - [Nintendo - Game Boy](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Game%20Boy.rdb) - [Nintendo - Game Boy Color](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Game%20Boy%20Color.rdb) - [Nintendo - Game Boy Advance](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Game%20Boy%20Advance.rdb) ## Features Frontend-level settings or features that the mGBA core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | [RetroArch SaveRAM Autosave Interval support](https://github.com/libretro/RetroArch/issues/16323#issuecomment-1977792161) | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✔ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Directories The mGBA core's library name is 'mGBA' The mGBA core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:----------------------:| | *.srm | Cartridge battery save | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ## Geometry and timing - The mGBA core's core provided FPS is [FPS] - The mGBA core's core provided sample rate is 32768 Hz - The mGBA core's base width is [Base width] - The mGBA core's base height is [Base height] - The mGBA core's max width is [Max width] - The mGBA core's max height is [Max height] - The mGBA core's core provided aspect ratio is [Aspect ratio] ## Core options The mGBA core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Solar sensor level** [mgba_solar_sensor_level] (**0**|1|2|3|4|5|6|7|8|9|10) Can be used by games that employed the use of a solar sensor on their cartridges. E.g.: Boktai games. - **Allow opposing directional input** [mgba_allow_opposing_directions] (**OFF**|ON) Allows opposing directional inputs. Up with Down. Right with Left. - **Game Boy model (requires restart)** [mgba_gb_model] (**Autodetect**|Game Boy|Super Game Boy|Game Boy Color|Game Boy Advance) Runs loaded content with a specific Game Boy model. Autodetect will select the most appropriate model for the current game. - **Use BIOS file if found** [mgba_use_bios] (**ON**|OFF) Uses BIOS present in RetroArch's system directory. Look at the [BIOS section](#bios) for more information. - **Skip BIOS intro** [mgba_skip_bios] (**OFF**|ON) **The 'Use BIOS file if found' core option must be set to On for proper operation.** Skips the BIOS intro when a BIOS is present in RetroArch's system directory is used. ??? note "Skip BIOS intro - Off" ![](../image/core/mgba/bios.png) - **Use Super Game Boy borders (requires restart)** [mgba_sgb_borders] (**ON**|OFF) Display Super Game Boy borders for Super Game Boy enhanced games. - **Idle loop removal** [mgba_idle_optimization] (**Remove Known**|Detect and Remove|Don't Remove) Optimizes game performance by driving the GBA's CPU less hard. Use this on low-powered hardware if its struggling with game performance. - **Frameskip** [mgba_frameskip] (**0**|1|2|3|4|5|6|7|8|9|10) Choose how much frames should be skipped to improve performance at the expense of visual smoothness. ## Rumble Rumble only works in the mGBA core when - The content being ran has rumble support. (e.g. Cartridges with a Rumble Pak) - The frontend being used has rumble support. - The joypad device being used has rumble support. ## Joypad ![](../image/controller/gba.png) | User 1 input descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Turbo B | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | Up | ![](../image/retropad/retro_dpad_up.png) | | Down | ![](../image/retropad/retro_dpad_down.png) | | Left | ![](../image/retropad/retro_dpad_left.png) | | Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | Turbo A | ![](../image/retropad/retro_x.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | | Turbo L | ![](../image/retropad/retro_l2.png) | | Turbo R | ![](../image/retropad/retro_r2.png) | | Darken Solar Sensor | ![](../image/retropad/retro_l3.png) | | Brighten Solar Sensor | ![](../image/retropad/retro_r3.png) | ## Compatibility Please file game bugs on the issue tracker [here](https://github.com/mgba-emu/mgba/issues) ## External Links - [Official mGBA Website](https://mgba.io/) - [Official mGBA Github Repository](https://github.com/mgba-emu/mgba) - [Libretro mGBA Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mgba_libretro.info) - [Libretro mGBA Github Repository](https://github.com/libretro/mgba) - [Report Libretro mGBA Core Issues Here](https://github.com/mgba-emu/mgba/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0Id2gXuMPiXpnjQmDuvg7Wli) ### See also #### Nintendo - Game Boy Advance - [Nintendo - Game Boy Advance (Beetle GBA)](beetle_gba.md) - [Nintendo - Game Boy Advance (gpSP)](gpsp.md) - [Nintendo - Game Boy Advance (Meteor)](meteor.md) - [Nintendo - Game Boy Advance (VBA Next)](vba_next.md) - [Nintendo - Game Boy Advance (VBA-M)](vba_m.md) #### Nintendo - Game Boy (+ Color) - [Nintendo - Game Boy / Color (Emux GB)](emux_gb.md) - [Nintendo - Game Boy / Color (Gambatte)](gambatte.md) - [Nintendo - Game Boy / Color (Gearboy)](gearboy.md) - [Nintendo - Game Boy / Color (SameBoy)](sameboy.md) - [Nintendo - Game Boy / Color (TGB Dual)](tgb_dual.md) - [Nintendo - SNES / Famicom (higan Accuracy)](higan_accuracy.md) - [Nintendo - SNES / Famicom (nSide Balanced)](nside_balanced.md) - [Nintendo - SNES / Famicom (Mesen-S)](mesen-s.md) ================================================ FILE: docs/library/microw8.md ================================================ # MicroW8 ## Background - MicroW8 is a WebAssembly based fantasy console usable for size-coding or larger games. The MicroW8 core has been authored by - [Dennis Ranke](https://github.com/exoticorn) - [Kivutar](https://github.com/kivutar) The MicroW8 core is licensed under - [Unlicense](https://github.com/libretro/uw8-libretro/blob/main/UNLICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the MicroW8 core have the following file extensions: - .uw8 - .wasm RetroArch database(s) that are associated with the MicroW8 core: - [MicroW8](https://github.com/libretro/libretro-database/blob/master/rdb/MicroW8.rdb) ## Features Frontend-level settings or features that the MicroW8 core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✕ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Geometry and timing - The MicroW8 core's core provided FPS is 60. - The MicroW8 core's core provided sample rate is 44100. - The MicroW8 core's base width is 320. - The MicroW8 core's base height is 240. - The MicroW8 core's max width is 320. - The MicroW8 core's max height is 240. - The MicroW8 core's core provided aspect ratio is 4/3. ## User 1 device types The MicroW8 core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): - None - Doesn't disable input. - **RetroPad** ## Joypad | RetroPad Inputs | MicroW8 inputs | |------------------------------------------------|--------------------------| | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | | ![](../image/retropad/retro_x.png) | Button X | | ![](../image/retropad/retro_y.png) | Button Y | | ![](../image/retropad/retro_a.png) | Button A | | ![](../image/retropad/retro_b.png) | Button B | ## External Links - [Official Website](https://exoticorn.github.io/microw8) - [Libretro MicroW8 core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/uw8_libretro.info) - [Libretro MicroW8 repository](https://github.com/libretro/uw8-libretro) - [Report Libretro MicroW8 core issues here](https://github.com/libretro/uw8-libretro/issues) - [MicroW8 games](https://itch.io/games/tag-microw8) ================================================ FILE: docs/library/minivmac.md ================================================ # Macintosh (minivmac) ## Background Minivmac is the build system for Mini vMac, a miniature Macintosh emulator. Further information may be found at "https://www.gryphel.com/c/minivmac/". ### Author/License The minivmac core has been authored by - phcoder - rtype The minivmac core is licensed under - [](https://github.com/libretro/libretro-minivmac) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the minivmac core have the following file extensions: - .dsk - .img - .zip - .hvf - .cmd ## Databases *WIP* RetroArch database(s) that are associated with the minivmac core: ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:---------------:|:----------------------:|:--------------------------------:| | MacII.rom | | 66223BE1497460F1E60885EEB35E03CC | ## Features Frontend-level settings or features that the minivmac core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✕ | | Screenshots | ✔ | | Saves | ✕ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The minivmac core's library name is 'minivmac' The minivmac core saves/loads to/from these directories. ### Geometry and timing - The minivmac core's core provided FPS is 13.63. - The minivmac core's core provided sample rate is 22255 Hz. - The minivmac core's base width is 1440. - The minivmac core's base height is 1080. - The minivmac core's core provided aspect ratio is 4/3. ## Core options The minivmac core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Status Bar** [minivmac_Statusbar] (**ON**|OFF) - **Keyboard Type** [minivmac_kbdtype] (**Callback**|Poll) ## Controllers The minivmac core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. There's no reason to switch to this. - **RetroPad** - Joypad - Minivmac Joystick - Joypad - Awaiting description. - Minivmac Keyboard - Keyboard inputs are always active. Has keymapper support. ### Controller tables #### Keyboard | RetroKeyboard Inputs | RetroKeyboard | |------------------------------|-----------------------| | Keyboard Backspace | BACKSPACE | | Keyboard Tab | TAB | | Keyboard Return | RETURN | | Keyboard Pause | PAUSE | | Keyboard Escape | ESCAPE | | Keyboard Space | SPACE | | Keyboard Quote ' | COLON | | Keyboard Comma , | COMMA | | Keyboard Minus - | NEGATIVE | | Keyboard Period . | PERIOD | | Keyboard Slash / | DIVIDE | | Keyboard 0 | 0 | | Keyboard 1 | 1, Player 1 Coleco #0 | | Keyboard 2 | 2, Player 1 Coleco #9 | | Keyboard 3 | 3, Player 2 Coleco #0 | | Keyboard 4 | 4, Player 2 Coleco #9 | | Keyboard 5 | 5 | | Keyboard 6 | 6 | | Keyboard 7 | 7 | | Keyboard 8 | 8 | | Keyboard 9 | 9 | | Keyboard Semicolon ; | SEMICOLON | | Keyboard Equals = | CIRCUMFLEX | | Keyboard Left Bracket [ | LEFT BRACKET | | Keyboard Backslash \ | BACKSLASH (YEN) | | Keyboard Right Bracket ] | RIGHT BRACKET | | Keyboard Backquote ` | AT | | Keyboard a | A | | Keyboard b | B | | Keyboard c | C | | Keyboard d | D | | Keyboard e | E | | Keyboard f | F | | Keyboard g | G | | Keyboard h | H | | Keyboard i | I | | Keyboard j | J | | Keyboard k | K | | Keyboard l | L | | Keyboard m | M | | Keyboard n | N | | Keyboard o | O | | Keyboard p | P | | Keyboard q | Q | | Keyboard r | R | | Keyboard s | S | | Keyboard t | T | | Keyboard u | U | | Keyboard v | V | | Keyboard w | W | | Keyboard x | X | | Keyboard y | Y | | Keyboard z | Z | | Keyboard Delete | DELETE | | Keyboard Keypad 0 | NUMPAD 0 | | Keyboard Keypad 1 | NUMPAD 1 | | Keyboard Keypad 2 | NUMPAD 2 | | Keyboard Keypad 3 | NUMPAD 3 | | Keyboard Keypad 4 | NUMPAD 4 | | Keyboard Keypad 5 | NUMPAD 5 | | Keyboard Keypad 6 | NUMPAD 6 | | Keyboard Keypad 7 | NUMPAD 7 | | Keyboard Keypad 8 | NUMPAD 8 | | Keyboard Keypad 9 | NUMPAD 9 | | Keyboard Keypad Period . | NUMPAD COMMA | | Keyboard Keypad Divide / | NUMPAD DIVIDE | | Keyboard Keypad Multiply * | NUMPAD MULTIPLY | | Keyboard Keypad Minus - | NUMPAD SUBTRACTION | | Keyboard Keypad Plus + | NUMPAD ADD | | Keyboard Keypad Enter | NUMPAD PERIOD | | Keyboard Up | UP | | Keyboard Down | DOWN | | Keyboard Right | RIGHT | | Keyboard Left | LEFT | | Keyboard Insert | INSERT | | Keyboard Home | CLS | | Keyboard End | STOP | | Keyboard Page Up | SELECT | | Keyboard F1 | F1 | | Keyboard F2 | F2 | | Keyboard F3 | F3 | | Keyboard F4 | F4 | | Keyboard F5 | F5 | | Keyboard Caps Lock | CAPS | | Keyboard Right Shift | RIGHT SHIFT | | Keyboard Left Shift | LEFT SHIFT | | Keyboard Left Control | CONTROL | | Keyboard Left Alt | GRAPH | | Keyboard Print | PRINT | Supported combinations ## External Links - [Official minivmac Website](https://www.gryphel.com/c/minivmac/) - [minivmac Repository](https://github.com/rickyzhang82/minivmac) - [Libretro minivmac Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/minivmac_libretro.info) - [Libretro minivmac Github Repository](https://github.com/libretro/libretro-minivmac) - [Report Libretro minivmac Core Issues Here](https://github.com/libretro/libretro-minivmac/issues) ================================================ FILE: docs/library/mkxp-z.md ================================================ # RPG Maker XP/VX/VX Ace (mkxp-z) ## Background Open-source cross-platform player for (some) RPG Maker XP / VX / VX Ace games. A very heavily modified fork of mkxp. RGSS on steroids with a stupid name. ### Author/License The mkxp-z core has been authored by: - [Aeodyn](https://github.com/Aeodyn) <Aeodyn0@gmail.com> - [Alex Folland](https://github.com/AlexFolland) <lexlexlex@gmail.com> - [Amaryllis Kulla](https://github.com/Ancurio) <ancurio@mapleshrine.eu> - [Thomas Schneider](https://github.com/BlackLotus) - [Carsten Teibes](https://github.com/carstene1ns) <dev@f4ke.de> - [cremno](https://github.com/cremno) <cremno@mail.ru> - [David Salvisberg](https://github.com/Daverball) <dave@daverball.com> - [Eblo](https://github.com/Eblo) - [Eliza Velasquez](https://github.com/elizagamedev) - [Jáchym Toušek](https://github.com/enumag) <enumag@gmail.com> - [ijuintekka](https://github.com/ijuintekka) <ijuintekka@hotmail.com> - [Joni Savolainen](https://github.com/jonisavo) <joni@savolainen.io> - [Luis Cáceres](https://github.com/lacc97) <lacc97@protonmail.ch> - [mook](https://github.com/mook) - [Nathan de Medeiros Vieira](https://github.com/Nathan-MV) <nathanmvieira@outlook.com> - [Riley Pierce](https://github.com/rainefall) <rileyraine01@gmail.com> - [Rodrigo Locatti](https://github.com/ReinUsesLisp) <rodrigo.locatti@gmail.com> - [Splendide Imaginarius](https://github.com/Splendide-Imaginarius) - Struma <strumajen@icloud.com> - [Edward Rudd](https://github.com/urkle) <urkle@outoforder.cc> - [Wayward Heart](https://github.com/WaywardHeart) - [Hao Liu (刘皓)](https://github.com/white-axe) <whiteaxe@tuta.io> The mkxp-z core is licensed under: - [GPLv2](https://github.com/mkxp-z/mkxp-z/blob/dev/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Requirements Currently, the mkxp-z core requires hardware that supports OpenGL 2.0 or later or OpenGL ES 2.0 or later. ## BIOS Some RPG Maker games require RTPs (Run Time Packages), which are stock assets intended to be shared between games. There is one standard RTP for each RPG Maker version supported by the mkxp-z core (XP, VX, VX Ace), which can be downloaded from [https://www.rpgmakerweb.com/run-time-package](https://www.rpgmakerweb.com/run-time-package). The RTPs are distributed as Windows installers and need to be extracted before they can be used by the mkxp-z core. They can be extracted on many different operating systems using [innoextract](https://constexpr.org/innoextract/). The installers are also runnable in Wine, although innoextract is more convenient. Once extracted, the RTP files should consist of a directory which contains two subdirectories named "Audio" and "Graphics" and possibly other files and subdirectories. The directory that contains the "Audio" and "Graphics" subdirectories should be renamed to "Standard" (for RPG Maker XP), "RPGVX" (for RPG Maker VX) or "RPGVXAce" (for RPG Maker VX Ace) and placed into the "mkxp-z/RTP" subdirectory of the frontend's system directory. If done correctly, the directory structure should look like this: ``` [system directory] └── mkxp-z └── RTP ├── RPGVX │   ├── Audio │   ├── Fonts │   ├── Game.ico │   ├── Graphics │   ├── RGSS200J.dll │   ├── RGSS202E.dll │   └── RGSS202J.dll ├── RPGVXAce │   ├── Audio │   ├── Fonts │   ├── Game.ico │   └── Graphics └── Standard ├── Audio ├── Game.ico └── Graphics ``` The three files named Game.ico and the .dll files listed in the above directory tree are not required by the mkxp-z core. Feel free to delete them if you want. ## Extensions Content that can be loaded by the mkxp-z core have the following file extensions (see the [Usage](#usage) section for instructions on how to load games): - .ini - .json - .rxproj - .rvproj - .rvproj2 - .mkxpz - .zip - .7z RetroArch database(s) that are associated with the mkxp-z core: - [RPG Maker](https://github.com/libretro/libretro-database/blob/master/rdb/RPG%20Maker.rdb) - [RPG Maker thumbnails](https://github.com/libretro-thumbnails/RPG_Maker) ## Features Frontend-level settings or features that the mkxp-z core respects: | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ [^1] | | Netplay | ✔ [^1] | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ [^2] | | RetroArch Cheats | ✔ [^2] | | Native Cheats | ✔ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✔ | | Language | ✔ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Directories The mkxp-z core's library name is 'mkxp-z' The mkxp-z core saves/loads to/from these directories. **Frontend's Save directory** | Directory | Description | |:------------:|:-----------:| | mkxp-z/Saves/[game title] | This is the directory where the game's save files are saved to. The exact contents of the directory vary depending on the specific game being played. | **Frontend's System directory** | Directory | Description | |:------------:|:-----------:| | mkxp-z/Fonts | Any fonts that the game uses that are not found in the game files will be loaded from here as a fallback. Supported file extensions for fonts are .otf and .ttf. The names of the font files do not matter since the mkxp-z core matches fonts based on the font family name stored in the file. | | mkxp-z/RTP | This is where RTPs are loaded from. See the [BIOS](#bios) section for more details. | | mkxp-z/Scripts/Preload | Any preload scripts added to this directory can be toggled in the "Preload Scripts" section of the core options. Enabled preload scripts will be loaded in lexicographic order of the bytes in their file names prior to loading the game's scripts. | | mkxp-z/Scripts/Postload | Any postload scripts added to this directory can be toggled in the "Postload Scripts" section of the core options. In RPG Maker VX Ace games, enabled postload scripts will be loaded in lexicographic order of the bytes in their file names after the game's scripts are loaded but before the game starts running. Enabled postload scripts have no effect in RPG Maker XP and RPG Maker VX games. | ## Geometry and timing - The mkxp-z core's core provided FPS is 40 (RPG Maker XP) or 60 (RPG Maker VX, RPG Maker VX Ace). - The mkxp-z core's core provided sample rate is 44100 hertz. - The mkxp-z core's base width is 640 (RPG Maker XP) or 544 (RPG Maker VX, RPG Maker VX Ace). - The mkxp-z core's base height is 480 (RPG Maker XP) or 416 (RPG Maker VX, RPG Maker VX Ace). - The mkxp-z core's max width is 640 (RPG Maker XP) or 544 (RPG Maker VX, RPG Maker VX Ace). - The mkxp-z core's max height is 480 (RPG Maker XP) or 416 (RPG Maker VX, RPG Maker VX Ace). - The mkxp-z core's core provided aspect ratio is 4:3 (RPG Maker XP) or 17:13 (RPG Maker VX, RPG Maker VX Ace). ## Usage There are three ways to load games using the mkxp-z core: - Load the Game.ini or mkxp.json. - Create an empty file with the file extension .rxproj, .rvproj or .rvproj2 in the same directory as Game.ini and/or mkxp.json, and load that. This is intended to make it easier to deal with save states in RetroArch, since RetroArch's save states are named after the file you load as the game, so if you load Game.ini or mkxp.json, all the save states for every game will be named "Game" or "mkxp", which is really inconvenient. - Put the game into a zip or 7z archive with file extension .mkxpz, .zip or .7z and load that. Please note that the files inside the zip or 7z archive should be uncompressed if possible, especially .rgssad/.rgss2a/.rgss3a and .otf/.ttf files inside the archive, or the game will lag quite a bit from trying to seek compressed files. The game will still run, though, just very slowly. Preload scripts and postload scripts may be added to the mkxp-z/Scripts/Preload and mkxp-z/Scripts/Postload subdirectories of the libretro system directory. Each preload script and postload script added to these directories has its own core option for toggling it. If more than one preload script or postload script is enabled via the core options at the same time, they will be loaded in lexicographic order of the bytes in the file names, which is the same as the order in which they appear in the core options menu. The default set of preload scripts provided with mkxp-z is embedded in the core and available by default to remove the need to manually copy them into the preload script directory. Native cheats are run as Ruby scripts. They can be used, for example, to change the contents of `$game_switches`. ## Core options The mkxp-z core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. In addition to the core options shown below, there are also core options for changing the key bindings and the currently enabled preload scripts and postload scripts. - **Runtime: RGSS Version** (Restart) [mkxp-z_rgssVersion] (**inherit**|default|1|2|3) Specify the RGSS version to run under. By default, mkxp will try to guess the required version based on the game files. If this fails, the version defaults to 1. Changes will take effect after the core is reset. - **Runtime: Save State Size** (Restart) [mkxp-z_saveStateSize] (64|66|68|70|72|74|76|78|80|82|84|86|88|90|92|94|96|98|**100**|102|104|106|108|110|112|114|116|118|120|122|124|126|128|132|136|140|144|148|152|156|160|164|168|172|176|180|184|188|192|196|200|204|208|212|216|220|224|228|232|236|240|244|248|252|256|264|272|280|288|296|304|312|320|328|336|344|352|360|368|376|384|392|400|408|416|424|432|440|448|456|464|472|480|488|496|504|512|544|576|608|640|672|704|736|768|800|832|864|896|928|960|992|1024|1152|1280|1408|1536|1664|1792|1920|2048|2560|3072|3584|4096) Maximum size of each save state, in mebibytes. If the game uses more than this much memory, save state creation will fail. Changes to this setting will not take effect until the core is unloaded. - **Runtime: Debug** (Restart) [mkxp-z_debug] (enabled|**disabled**) Launch the game in debug mode. Changes will take effect after the core is reset. - **Runtime: Battle Test** (Restart) [mkxp-z_battleTest] (enabled|**disabled**) Launch the game in battle test mode. Changes will take effect after the core is reset. - **Video: Frame Skip** [mkxp-z_frameSkip] (inherit|enabled|**disabled**) Skip (don't draw) frames when behind. - **Video: Subimage Fix** [mkxp-z_subImageFix] (inherit|**default**|enabled|disabled) Work around buggy graphics drivers which don't properly synchronize texture access, most apparent when text doesn't show up or the map tileset doesn't render at all. (default: enabled for systems using OpenGL ES, disabled on other systems) - **Video: Framebuffer Blitting** [mkxp-z_enableBlitting] (inherit|**default**|enabled|disabled) Enable framebuffer blitting if the driver is capable of it. Some drivers carry buggy implementations of this functionality, so disabling it can be used as a workaround. (default: disabled on Windows, enabled on other systems) - **Video: Texture Synchronization** [mkxp-z_textureSync] (**default**|eager|lazy) Controls how often GPU textures are copied to CPU memory. Eager synchronization is less likely to cause graphical issues but may cause performance problems in some games. Lazy synchronization is faster but may or may not, depending on which libretro frontend you're using and what version of it you're using, cause graphical artifacts when performing certain operations, such as toggling fullscreen or, on Android, opening the app switcher. (default: lazy) - **Audio: Threaded Audio** (Restart) [mkxp-z_threadedAudio] (**enabled**|disabled) Use a worker thread for rendering the audio instead of rendering in the main thread, if possible. Reduces audio crackling, especially on systems with slow file system access speed. Changes to this setting will not take effect until the game is closed. - **Audio: MIDI Chorus** [mkxp-z_midiChorus] (**inherit**|enabled|disabled) Activate "chorus" effect for midi playback. - **Audio: MIDI Reverb** [mkxp-z_midiReverb] (**inherit**|enabled|disabled) Activate "reverb" effect for midi playback. - **Audio: SE Source Count** (Restart) [mkxp-z_SESourceCount] (**6**|7|8|9|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59|60|61|62|63|64) Number of OpenAL sources to allocate for SE playback. If there are a lot of sounds playing at the same time and audibly cutting each other off, try increasing this number. Changes will take effect after the core is reset. (if this value is also set in the game's mkxp.json, the maximum of the value set here and the value in mkxp.json will be used) - **Text: Font Scale** [mkxp-z_fontScale] (0.2|0.25|0.3|0.35|0.4|0.45|0.5|0.55|0.6|0.65|0.7|0.75|0.8|0.85|0.9|0.95|**1.0**|1.05|1.1|1.15|1.2|1.25|1.3|1.35|1.4|1.45|1.5|1.55|1.6|1.65|1.7|1.75|1.8|1.85|1.9|1.95|2.0|2.05|2.1|2.15|2.2|2.25|2.3|2.35|2.4|2.45|2.5|2.55|2.6|2.65|2.7|2.75|2.8|2.85|2.9|2.95|3.0|3.05|3.1|3.15|3.2|3.25|3.3|3.35|3.4|3.45|3.5|3.55|3.6|3.65|3.7|3.75|3.8|3.85|3.9|3.95|4.0|4.05|4.1|4.15|4.2|4.25|4.3|4.35|4.4|4.45|4.5|4.55|4.6|4.65|4.7|4.75|4.8|4.85|4.9|4.95|5.0) Scales the sizes of all fonts. If you think text tends to be too large or too small, try fiddling with this. (if this value is also set in the game's mkxp.json, the product of the value set here and the value in mkxp.json will be used) - **Text: Kerning** [mkxp-z_fontKerning] (**inherit**|default|enabled|disabled) Kerning adjusts the spacing between individual letters or characters. Enabling it generally looks nicer, but RGSS doesn't use it, so disabling it should make text appearance more accurate. (default: enabled) - **Text: Font Hinting** [mkxp-z_fontHinting] (**inherit**|default|0|1|2|3) Hinting adjusts the rendering of individual letters or characters. Enabling it may look nicer (especially on low-resolution displays), but RGSS doesn't use it, so disabling it should make text appearance more accurate. Documentation can be found at: https://pysdl2.readthedocs.io/en/latest/modules/sdl2_sdlttf.html#sdl2.sdlttf.TTF_HINTING_NORMAL (default: 3) - **Text: Font Height Reporting** [mkxp-z_fontHeightReporting] (**inherit**|default|0|1) Controls the algorithm for reporting the height of rendered text. 0: Nominal (TTF_FontHeight); matches RGSS behavior; may cut off bottoms of some characters. 1: Rendered (TTF_SizeUTF8); deviates from RGSS; may look better. (default: 0) - **Text: Outline Crop** [mkxp-z_fontOutlineCrop] (**inherit**|default|enabled|disabled) Crops top row and left column of text that has an outline. Disabling it generally looks nicer, but RGSS enables it, so enabling it should make text appearance more accurate. (default: enabled) - **Text: Load Fonts Into Memory** [mkxp-z_loadFontsIntoMemory] (**default**|enabled|disabled) When loading a font, load the entire font file into memory instead of using a file handle. This improves text rendering performance on systems with extremely slow file system access speed at the cost of higher memory usage. (default: enabled on Emscripten, disabled on other platforms) ## Joypad These are the default bindings. They can be changed in the "Button Bindings" section of the core options if needed. | RetroPad Inputs | RGSS Inputs | |------------------------------------------------|--------------------------| | ![](../image/retropad/retro_a.png) | Input::C | | ![](../image/retropad/retro_b.png) | Input::B | | ![](../image/retropad/retro_x.png) | Input::A | | ![](../image/retropad/retro_y.png) | Input::X | | ![](../image/retropad/retro_dpad_up.png) | Input::UP | | ![](../image/retropad/retro_dpad_down.png) | Input::DOWN | | ![](../image/retropad/retro_dpad_left.png) | Input::LEFT | | ![](../image/retropad/retro_dpad_right.png) | Input::RIGHT | | ![](../image/retropad/retro_l1.png) | Input::L | | ![](../image/retropad/retro_r1.png) | Input::R | | ![](../image/retropad/retro_l2.png) | Input::CTRL | | ![](../image/retropad/retro_r2.png) | Input::SHIFT | | ![](../image/retropad/retro_l3.png) | Input::Y | | ![](../image/retropad/retro_r3.png) | Input::Z | | ![](../image/retropad/retro_start.png) | Input::ALT | | ![](../image/retropad/retro_left_stick.png) X | Input::LEFT and Input::RIGHT | | ![](../image/retropad/retro_left_stick.png) Y | Input::UP and Input::DOWN | ## Mouse These are the default bindings. They can be changed in the "Button Bindings" section of the core options if needed. | RetroMouse Inputs | RGSS Inputs | |-------------------------------------------------------|---------------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Input.mouse_x and Input.mouse_y | | ![](../image/retromouse/retro_left.png) Mouse 1 | Input::MOUSELEFT | | ![](../image/retromouse/retro_right.png) Mouse 2 | Input::MOUSERIGHT | | ![](../image/retromouse/retro_middle.png) Mouse 3 | Input::MOUSEMIDDLE | | Mouse 4 | Input::MOUSEX1 | | Mouse 5 | Input::MOUSEX2 | | Wheel Up | Input.scroll_v | | Wheel Down | Input.scroll_v | ## External Links - [mkxp-z GitHub Repository](https://github.com/mkxp-z/mkxp-z) - [Libretro mkxp-z Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mkxp-z_libretro.info) - [Report Libretro mkxp-z Core Issues Here](https://github.com/mkxp-z/mkxp-z/issues) ## (Related cores) - [RPG Maker 2000/2003 (EasyRPG)](easyrpg.md) [^1]: Because RetroArch does not currently support rewind or netplay with cores that use threaded audio, rewind and netplay currently require disabling the ["Threaded Audio" core option](#core-options). This core option is enabled by default for better performance and for closer similarity to the original RPG Maker runtimes, which also use threaded audio. [^2]: Only supported on little-endian devices. ================================================ FILE: docs/library/mr_boom.md ================================================ # Mr.Boom (Bomberman) ## Background Mr.Boom is an up to 8 player Bomberman clone ported to the libretro API. The goal of the game is to bomb away your enemies and other players. The Mr.Boom core has been authored by - Remdy Software The Mr.Boom core is licensed under - [MIT](https://github.com/libretro/mrboom-libretro/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions The Mr.Boom core does not feature extension use. Just load and start the core. ## Features | Feature | Supported | |-------------------|:---------:| | Saves | ✕ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controllers | ✔ | | Remapping | ✕ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | The Mr.Boom core's directory name is 'Mr.Boom' Save states are saved/loaded to and from where state files are stored. ### Geometry and timing - The Mr. Boom core's core provided FPS is 60 - The Mr. Boom core's core provided sample rate is 48000 Hz - The Mr. Boom core's core provided base width is 320 - The Mr. Boom core's core provided base height is 200 - The Mr. Boom core's core provided aspect ratio is 8/5 (native), 4/3 or 16/9 ## Core options *The Mr.Boom core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded.* - **Team mode** (**Selfie**/Color/Sex): Team mode color. - **Monsters** (Off/**On**): Awaiting description. Enable or disable monsters. ??? note "Monsters - On" ![](../image/core/mr_boom/monsters_on.png) ??? note "Monsters - Off" ![](../image/core/mr_boom/monsters_off.png) - **Drop bomb autofire** (**Off**/On): Enables Drop bomb autofire mode. Holding down the Drop bomb button will repeatedly use the Drop bomb action. (Potentially useful when used in conjunction with certain powerups) ## Controllers *The Mr.Boom core supports the following controller setting(s), bolded controller settings are the default for the specified user(s):* ### User 1 - 16 Device Type(s) * **RetroPad** - Joypad with analog * RetroPad w/Analog - **There is no reason to switch to this.** ### Controllers graph | RetroPad Inputs | Mr.Boom core inputs | |------------------------------------------------|---------------------| | ![](../image/retropad/retro_b.png) | Drop Bomb/Join game | | ![](../image/retropad/retro_select.png) | Add a bomberman bot (while in the join game screen) | | ![](../image/retropad/retro_start.png) | Start game | | ![](../image/retropad/retro_dpad_up.png) | Up/Push bomb | | ![](../image/retropad/retro_dpad_down.png) | Down/Push bomb | | ![](../image/retropad/retro_dpad_left.png) | Left/Push bomb | | ![](../image/retropad/retro_dpad_right.png) | Right/Push bomb | | ![](../image/retropad/retro_a.png) | Detonate bomb (when you have the Remote control power)/Join game | | ![](../image/retropad/retro_x.png) | Jump (while riding a Kangaroo)/Join game) | ## External Links * [Libretro Mr.Boom Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mrboom_libretro.info) * [Libretro Mr.Boom Repository](https://github.com/libretro/mrboom-libretro) * [Report Core Issues Here](https://github.com/libretro/libretro-meta) * [Official Website](http://mrboom.mumblecore.org/) * [Upstream Repository](https://github.com/Javanaise/mrboom-libretro) ================================================ FILE: docs/library/mu.md ================================================ # Palm OS (Mu) ## Background Mu is the first Palm OS emulator capable of actually playing Palm games. It is currently capable of playing most 160×160 Palm OS 4 software perfectly. There are a few hardware abstraction glitches and sound FIFO inaccuracies but other than that the device works and the audio plays normally, with no hacks done to the OS. The Mu core has been authored by: - guicrith / meepingsnesroms; Stephanie Gawroriski (Xer Shadow Tail) The Mu core is licensed under: - [CC BY-NC 3.0 US (Non-commercial)](http://creativecommons.org/licenses/by-nc/3.0/us/) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS [Required or optional firmware files](https://docs.libretro.com/library/bios/) go in the frontend's system directory: | Filename | Description | md5sum | |:-----------------:|:-------------------------------:|:--------------------------------:| | `palmos40-en-m500.rom` | Palm OS 4.0 for m500 | `f50e4d5e4d98dc831f2c34a9107651eb` | | `palmos41-en-m515.rom` | Palm OS 4.1 for m515 | `83cb1d1c76e568b916dc2e7c0bf669f6` | | `palmos52-en-t3.rom` | Palm OS 5.2 for Tungsten T3 | `de46ec84d9aabf655eabdf9b00a3845d` | | `bootloader-dbvz.rom` | | `9da101cd2317830649a31f8fa46debec` | The BIOS file corresponding to the selected model is required, default is the m515. ## Extensions Content that can be loaded by the Mu core have the following file extensions: - `.prc`, `.pqa`, `.pdb` - `.zip` - `.img` - image file for the MMC card RetroArch database(s) that are associated with the Mu core: none yet. ## Features Frontend-level settings or features that the Mu core respects: | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✕ | | States | ✔ | | Rewind | - | | Netplay | - | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | - | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✔ | ## Geometry and timing - The Mu core's core provided FPS is 60 - The Mu core's core provided sample rate is 48000 - The Mu core's base width is 160 - The Mu core's base height is 220 - The Mu core's max width is 320 - The Mu core's max height is 480 - The Mu core's core provided aspect ratio is 8:11 ## Core options The Mu core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Core has to be closed for all settings to be applied on next launch. - CPU Speed (**1.0**|1.5|2.0|2.5|3.0|0.5) - Force Match System Clock (**disabled**|enabled) - Ignore Invalid Behavior (**disabled**|enabled) - Use Left Joystick As Mouse (**disabled**|enabled) - Disable Graffiti Area (**disabled**|enabled) - OS Version (**Palm m515/Palm OS 4.1**|Tungsten T3/Palm OS 5.2.1|Tungsten T3/Palm OS 6.0|Palm m500/Palm OS 4.0) ## Joypad | RetroPad Inputs | Palm OS Inputs | |------------------------------------------------|----------------| | ![](../image/retropad/retro_b.png) | To Do List | | ![](../image/retropad/retro_y.png) | Date Book | | ![](../image/retropad/retro_select.png) | D-Pad Center | | ![](../image/retropad/retro_start.png) | Power | | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left (OS5 only) | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right (OS5 only) | | ![](../image/retropad/retro_a.png) | Note Pad | | ![](../image/retropad/retro_x.png) | Address Book | | ![](../image/retropad/retro_r1.png) | Touchscreen click/tap | | ![](../image/retropad/retro_left_stick.png) | Touchscreen movement | ## Pointer | RetroPointer Inputs | Palm OS Inputs | |--------------------------------------------------------------------------------------------------------------------------|---------------------------| | ![](../image/retromouse/retro_mouse.png) or ![](../image/Button_Pack/Gestures/Gesture_Finger_Front.png) Pointer Position | Touchscreen movement | | ![](../image/retromouse/retro_left.png) or ![](../image/Button_Pack/Gestures/Gesture_Tap.png) Pointer Pressed | Touchscreen click/tap | ## External Links - [Original Mu Website](https://meepingsnesroms.github.io/) - [Original Mu Repository](https://github.com/meepingsnesroms/Mu) - [Libretro Mu Core info file](https://github.com/libretro/Mu/blob/master/libretroBuildSystem/mu_libretro.info) - [Libretro Mu Repository](https://github.com/libretro/Mu) - [Report Libretro Mu Core Issues Here](https://github.com/libretro/Mu/issues) ================================================ FILE: docs/library/mupen64plus.md ================================================ # Nintendo 64 (Mupen64Plus-Next) ## Background Mupen64Plus-Next for libretro is an up-to-date port of Mupen64Plus, a Nintendo 64 emulator. Mupen64Plus-Next for libretro uses GLideN64 as its default graphic plugin, though Angrylion and ParaLLEl-RDP plugs are also available. For Android there are two versions of Mupen64Plus-Next. One is designed to work with GLES 2.0 and another one with GLES 3.0, and the GLES 2.0 version will have graphical issues on a GLES 3.0-compatible system. How is this different from Parallel-N64? Parallel-N64 was forked off from the standalone Mupen64Plus codebase a number of years ago, and it has diverged fairly significantly since then. Also, the graphic plugin GLideN64 is not available in Parallel-N64. This core has the latest upstream accuracy improvements, along with the latest and greatest HLE improvements in GLideN64 and the latest LLE developments in ParaLLEl-RDP/RSP. Outstanding support of Hires Textures. The Mupen64Plus-Next core has been authored by - m4xw - gillou - gonetz - Hacktarux - Mupen64Plus Team The Mupen64Plus-Next core is licensed under - [GPLv3](https://github.com/libretro/mupen64plus-libretro/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Mupen64plus-Next core have the following file extensions (*.gb via Transfer Pak emulation): - .n64 - .v64 - .z64 - .bin - .u1 - .ndd - .gb ## Databases RetroArch database(s) that are associated with the Mupen64plus-Next core: - [Nintendo - Nintendo 64](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%2064.rdb) - [Nintendo - Nintendo 64DD](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%2064DD.rdb) ## Features RetroArch-level settings or features that the Mupen64plus-Next core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✔ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✔ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | ### Directories The Mupen64plus-Next core's directory name is 'Mupen64Plus-Next' The Mupen64plus-Next core saves/loads to/from these directories. **RetroArch's Save directory** - 'content-name'.srm (Cartridge backup save) **RetroArch's State directory** - 'content-name'.state# (State) **RetroArch's System directory** ``` - Mupen64plus/ - mupen64plus.ini - shaders/ ``` ### Geometry and timing - The Mupen64plus-Next core's internal FPS is (FPS) - The Mupen64plus-Next core's internal sample rate is 44100 Hz - The Mupen64plus-Next core's core provided aspect ratio is (Ratio) ### High-Resolution Textures There are two primary ways to utilize high-resolution textures: 1. By using pre-compiled high-resolution texture packs (in the `.htc` format) that are available for download. 2. By compiling your own high-resolution texture packs from uncompressed Rice sources. #### Use Pre-Compiled High-Resolution Textures - Place the `.htc` formatted textures into the `Mupen64plus/cache` directory. - Ensure the `.htc` file name corresponds to the system name of the game as shown in the mupen64plus console. - Pre-compiled high-resolution packs will work only if Retroarch core settings related to textures match those used during the pack's compilation. To avoid potential mismatches, you might prefer to compile your own texture packs. **Recommended core options** for widely used `.htc` texture packs (for example, those used by Djipi or Mollymutt): - `mupen64plus-EnableTextureCache = "True"` - `mupen64plus-txHiresEnable = "True"` - `mupen64plus-txCacheCompression = "True"` - `mupen64plus-txHiresFullAlphaChannel = "False"` - `mupen64plus-EnableEnhancedTextureStorage = "False"` - `mupen64plus-EnableEnhancedHighResStorage = "False"` #### Compile Your Own High-Resolution Texture Packs 1. Obtain the high-resolution textures in uncompressed Rice format. 2. Name the folder to match the system name of the game in the mupen64plus console and place it in the `Mupen64plus/hires_texture` directory. 3. When you first launch the game, the `.htc` texture pack will be created. This process can take some time. 4. After the `.htc` file is successfully generated in the cache subdirectory, you can remove the uncompressed texture directory, as it becomes redundant. For custom compilations, enabling the additional options for Alpha Channel and Enhanced Storage will yield a high-resolution texture pack with an `*.hts` extension. If you're planning to use your custom texture pack on a different system, ensure that you activate the same core options for textures on the new system as those you set during the compilation. **Note**: Compilation on Windows can be more intricate than on Linux or iOS. Ensure Rice texture packs are converted to 32-bit PNG. ## Using the Transfer Pak First you have to virtually plug the Transfer Pak, so start a N64 game, then **Quick Menu > Options > Player 1 Pak > transfer** and close content, then there are 2 ways of loading: ### Renaming the GB save and the GB rom to match the N64 rom filename and having the 3 files in the same folder So for example if you have Pokemon Stadium (USA).z64, in the same folder you'll have: - Pokemon Stadium (USA).z64 (the N64 rom). - Pokemon Stadium (USA).z64.sav (the GB save, change the .srm extension to .sav if needed, it won't work with .srm). - Pokemon Stadium (USA).z64.gb (the GB rom, if it's a GBC rom you'll need to rename .gbc to .gb). - So it should look [like this](https://i.imgur.com/U4fBma3.png). If you're on Windows, [make sure you don't have the extensions hidden](https://www.howtogeek.com/205086/beginner-how-to-make-windows-show-file-extensions/) - And then just load the .z64 file with Mupen64 core :) ### Using subsystems - Go to **retroarch/saves/**, make a copy of your GB *.srm save file and rename it to *.sav (e.g. Pokemon Red.srm -> Pokemon Red.sav). - Now go to **Main Menu > Load Core** and load Mupen64Plus-Next. It will load the core without content. - Go to **Main Menu > Subsystems > Load N64 Transferpak** and load the .sav file. - Now, go back to **Subsystems** menu and load the *.gb file this time. - Go back to **Subsystems** menu again and this time load the N64 rom. - Go to **Subsystems** AGAIN (last time!) and click **Start N64 Transferpak**. If done properly [you should see the .sav, the .gb and the .z64 listed](https://i.imgur.com/v1vTGQT.png). ## Core options The Mupen64plus-Next core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **CPU Core** (**dynamic_recompiler**/cached_interpreter/pure_interpreter) Choose which kind of CPU emulation is going to be used. Dynamic recompiler is the fastest mode. **Dynamic recompilier is not available on all platforms.** - **RSP Mode** (**HLE**/LLE) How the RSP is emulated, High Level Emulation or Low Level Emulation. Low level emulation should be more precise but it requires more computational power. **LLE mode is not available on all platforms** - **4:3 Resolution** (**320x240**/ 640x480/ 960x720/ 1280x960/ 1600x1200/ 1920x1440/ 2240x1680/ 2560x1920/ 2880x2160/ 3200x2400/ 3520x2640/ 3840x2880) Select the internal rendering resolution for 4:3 Aspect Ratio mode. The 'Aspect Ratio' core option must be set to 4:3 for this to have an effect. Higher values require more computational power. - **16:9 Resolution** (**640x360**/ 960x540/ 1280x720/ 1920x1080/ 2560x1440/ 3840x2160/ 7680x4320) Select the internal rendering resolution for 16:9 Aspect Ratio mode. The 'Aspect Ratio' core option must be set to 16:9 or 16:9 adjusted for this to have an effect. Higher values require more computational power. - **Aspect Ratio** (**4:3**/16:9/16:9 adjusted) This setting adjusts the aspect ratio of the video output. All N64 games support 4:3. Some games support 16:9 within game settings. - **Bilinear filtering mode** (**standard**/3point) Bilinear filtering: Textures will use standard PC-style bilinear filtering. 3 point: Textures will be filtered more like the N64. The result is less smooth but more accurate. - **MSAA level** (0/2/4/8/16) Enable/Disable MultiSampling Anti-aliasing (0=off, 2,4,8,16=quality). **This core option is not available on all platforms.** - **Framebuffer Emulation** (**True**/False) Enable the framebuffer emulation. Frame buffer emulation is a set of techniques used to emulate manipulations with color and depth buffer areas on the real console. Unchecking this option disables many effects including cropping, aspect ratio, N64 resolution factor and more. Do not uncheck this option unless you have performance issues. - **Color buffer to RDRAM** (**Async**/Sync/Off) Used with the framebuffer emulation. Frame buffer copy is used for some effects (e.g. TV monitor effect where TV shows part of the displayed picture). In some games GLideN64 cannot detect when the game uses the frame buffer. With these options, you can have GLideN64 copy each frame of your video cards frame buffer to N64 memory. Off: Disable copying buffers from video card. Synchronous: Effects are detected for all games, but it can be slow. Use for games where Asynchronous does not work. Asynchronous: Effects are detected for most games (best choice). The default setting is dependent on your platform. - **Depth buffer to RDRAM** (**Software**/FromMem/Off) Used with the framebuffer emulation. The depth buffer is used to emulate some effects (e.g. coronas). Off: Depth buffer is disabled. FromMem: Your video card’s depth buffer is copied to N64 memory each frame, which can be slow on some games. Software: Generally faster than copying from VRAM, but the result can be imperfect. - **Hardware per-pixel lighting** (**False**/True) In N64 games lighting is calculated per vertex. This option enables hardware per-pixel lighting calculation known as Phong shading, which provides smoother and more realistic lighting. Per-vertex lighting is instead calculated via software. HLE only. - **Continuous texrect coords** (**Off**/Auto/Force) In some games the coordinates for parts of 2D elements are not aligned: there is a half-pixel split between adjacent elements. When rendering at the N64’s original resolution it is not visible, but when the image is scaled up it results in black lines. This option attempts to connect these 2D elements. - **Native res. 2D texrects** (**False**/True) When checked, 2D elements are rendered at the N64s resolution before copying them to output. This usually eliminates display issues with 2D elements, but it can be slow. This option uses heuristics to detect adjacent 2D elements that does not work for every game. - **Less accurate blending mode** (**True**/False) Do not use shaders to emulate N64 blending modes. Works faster on slow GPU. It can cause glitches. The default setting is dependent on your platform. - **GPU shader depth write** (**False**/True) Enable writing of fragment depth. Some mobile GPUs do not support it, thus it made optional. The default setting is dependent on your platform. - **Cache GPU Shaders** (**True**/False) When the option is enabled, plugin saves all new created shaders in a file. When user starts that game again, plugin loads all previously compiled shaders from that file and further gameplay goes smooth. - **Crop Mode** (**Auto**/Off) Its purpose is to remove black borders, which many N64 games add around image. In auto mode plugins tries to detect empty space and remove it. It works only if frame buffer emulation is enabled, as all other post-processing filters. - **Texture filter** (**None**/Smooth filtering 1/Smooth filtering 2/Smooth filtering 3/Smooth filtering 4/Sharp filtering 1/Sharp filtering 2) This filter smooths or sharpens textures. There are four smoothing filters and two sharpening filters. The higher the number, the stronger the effect. Performance may be affected depending on the game and/or your device. - **Texture Enhancement** (**None**/As Is/X2/X2SAI/HQ2X/HQ2XS/LQ2X/LQ2XS/HQ4X/2xBRZ/3xBRZ/4xBRZ/5xBRZ/6xBRZ) Filter applied to textures. Depending on which filter, they may cause performance problems. When AS IS is selected, textures are saved to the cache as-is; this improves performance in games that load many textures; unset Filer background textures for the best performance. - **Filter background textures** (**True**/False) This option skips texture enhancements for long, narrow textures that are usually used for backgrounds. This may save texture memory and improve performance. Set true unless Enhancement mode is set to AS IS. - **Use High-Res textures** (**False**/True) Enable the high resolution textures. Usage of hires textures is explained above. - **Use High-Res Full Alpha Channel** (**False**/True) When this option is selected, GlideN64 will check how the texture’s alpha channel was designed and will select the most appropriate format. This gives texture pack designers freedom to use semi-transparent textures. Clear this option for older or poorly designed texture packs. Recommended for newer texture packs. - **Analog Deadzone (percent)** (**15**/20/25/30/0/5/10) The minimum absolute value of SDL analog Joystick axis to move the N64 controller axis value - **Analog Sensitivity (percent)** (**100**/95/90/85/80/105/110) The sensitivity of the analog Joystick. - **Right C Button** (**C1**/C2/C3/C4) Awaiting description. - **Left C Button** (**C2**/C3/C4/C1) Awaiting description. - **Down C Button** (**C3**/C4/C1/C2) Awaiting description. - **Up C Button** (**C4**/C1/C2/C3) Awaiting description, - **Player 1 Pak** (**memory**/rumble/none) Choose what Pak has been inserted in the player 1 controller. - **Player 2 Pak** (**none**/memory/rumble) Choose what Pak has been inserted in the player 2 controller. - **Player 3 Pak** (**none**/memory/rumble) Choose what Pak has been inserted in the player 3 controller. - **Player 4 Pak** (**none**/memory/rumble) Choose what Pak has been inserted in the player 4 controller. - **Count Per Op** (0/1/2/3) Force the number of cycle per emulated instructions. ## Controllers ### Device types The Mupen64plus-Next core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): #### User 1 - 4 device types - None - Input disabled. - **Controller** - Joypad ### Rumble support Rumble only works in the Mupen64plus-Next core when - The content being ran has rumble support. - The joypad input driver being used has rumble support. (e.g. Xinput) - The joypad device being used has rumble support. - The 'Player # Pak' core options are set to rumble for the respective players. [List of Nintendo 64 games with Rumble Pak support](http://nintendo.wikia.com/wiki/List_of_Nintendo_64_games_with_Rumble_Pak_support) ### Controller tables #### Joypad and analog device type table | User 1 - 4 Remap descriptors | RetroPad Inputs | |-------------------------------|----------------------------------------------| | A Button (C3) | ![](../image/retropad/retro_b.png) | | B Button (C2) | ![](../image/retropad/retro_y.png) | | START Button | ![](../image/retropad/retro_start.png) | | Up (digital) | ![](../image/retropad/retro_dpad_up.png) | | Down (digital) | ![](../image/retropad/retro_dpad_down.png) | | Left (digital) | ![](../image/retropad/retro_dpad_left.png) | | Right (digital) | ![](../image/retropad/retro_dpad_right.png) | | (C1) | ![](../image/retropad/retro_a.png) | | (C4) | ![](../image/retropad/retro_x.png) | | L-Trigger | ![](../image/retropad/retro_l1.png) | | R-Trigger | ![](../image/retropad/retro_r1.png) | | Z-Trigger | ![](../image/retropad/retro_l2.png) | | C Buttons Mode | ![](../image/retropad/retro_r2.png) | | Control Stick X | ![](../image/retropad/retro_left_stick.png) X | | Control Stick Y | ![](../image/retropad/retro_left_stick.png) Y | | C Buttons X | ![](../image/retropad/retro_right_stick.png) X | | C Buttons Y | ![](../image/retropad/retro_right_stick.png) Y | ## Compatibility Awaiting description. ## External Links - [Libretro Mupen64plus-Next Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/mupen64plus_next_libretro.info) - [Libretro Mupen64plus-Next Github Repository](https://github.com/libretro/mupen64plus-libretro-nx) - [Report Libretro Mupen64plus-Next Core Issues Here](https://github.com/libretro/mupen64plus-libretro-nx/issues) - [Official Mupen64Plus Website](http://www.mupen64plus.org/) - [Official Mupen64Plus Github Organization](https://github.com/mupen64plus) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0IeBgJ8wFAH6Oh9aDNC-MBuU) ## See also ================================================ FILE: docs/library/neko_project_ii_kai.md ================================================ # NEC - PC-98 (Neko Project II Kai) ## Background NP2kai is a PC-9801 series core. The NEC PC-9800, also known as the PC-98, were a family of computers made by NEC throughout 1982 to 2000. Despite using Intel x86 chips, MS-DOS and Windows OS, and many other superficial similarities, the series is not IBM compatible. Some PC-98 software may work on an IBM or vice versa, but this is very YMMV. In fact, the introduction of a native Japanese version of standard MS-DOS in the early 90s and subsequent entry of cheaper foreign IBM clones in the Japanese market was the nail in the coffin for the PC-98. They were not released or marketed outside of Japan (besides few attempts such as APC-III and PC-9801FC), but still useful for playing early visual novels and Touhou games. ### Author/License The Neko Project II Kai core has been authored by - Neko Project II Team - Tomohiro Yoshidomi The Neko Project II Kai core is licensed under - [MIT](https://github.com/AZO234/NP2kai/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Neko Project II Kai core have the following file extensions: - .d98 - .zip - .98d - .fdi - .fdd - .2hd - .tfd - .d88 - .88d - .hdm - .xdf - .dup - .cmd - .hdi - .thd - .nhd - .hdd - .hdn ## BIOS Required or optional firmware files go in the frontend's system directory. !!! attention These firmware files need to be in a directory named 'np2kai' in the frontend's system directory. | Filename | Description | md5sum | |:-------------------:|:---------------------------------:|:--------------------------------:| | np2kai/font.bmp | Needed to display text - Required | 7da1e5b7c482d4108d22a5b09631d967 | | np2kai/FONT.ROM | Alt font file - Required | 2af6179d7de4893ea0b705c00e9a98d6 | | np2kai/bios.rom | - Required | e246140dec5124c5e404869a84caefce | | np2kai/itf.rom | - Required | e9fc3890963b12cf15d0a2eea5815b72 | | np2kai/sound.rom | - Required | caf90f22197aed6f14c471c21e64658d | | np2kai/bios9821.rom | - Optional | | | np2kai/d8000.rom | - Optional | | | np2kai/2608_BD.WAV | YM2608 RYTHM sample - Optional | | | np2kai/2608_SD.WAV | YM2608 RYTHM sample - Optional | | | np2kai/2608_TOP.WAV | YM2608 RYTHM sample - Optional | | | np2kai/2608_HH.WAV | YM2608 RYTHM sample - Optional | | | np2kai/2608_TOM.WAV | YM2608 RYTHM sample - Optional | | | np2kai/2608_RIM.WAV | YM2608 RYTHM sample - Optional | | ## Features Frontend-level settings or features that the Neko Project II Kai core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✕ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✕ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✔ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Neko Project II Kai core's directory name is 'Neko Project II kai' The Neko Project II Kai core saves/loads to/from these directories. **Frontend's Home directory** - .bmp (???) **Frontend's State directory** - 'content-name'.state# (State) **Frontend's System directory** - np2/np2.cfg (Neko Project II Config file) ### Geometry and timing - The Neko Project II Kai core's core provided FPS is `56.4`. - The Neko Project II Kai core's core provided sample rate is `44100Hz`. - The Neko Project II Kai core's core provided aspect ratio is `8/5`. ## Usage NP2 menu can FDD/HDD swap. Mouse is cuptured (hidden/show toggle) by F11 key. NP2 menu is opened when F12 key Keep 'end' key down when booting for machine options. How to set GDC 2.5MHz/5MHz? 1. Press End key(assigned Help key) + reset 2. Select 'ディップスイッチ２'(DIP switch 2) How to use CD drive with MS-DOS 6.2? Write follow to CONFIG.SYS. ``` LASTDRIVE=Z DEVICE=A:￥DOS￥NECCDD.SYS /D:CD_101 ``` And write follow to AUTOEXEC.BAT. ``` A:￥DOS￥MSCDEX.EXE /D:CD_101 /L:Q ``` Then, you'll can use CD drive as Q drive. ## Core options The Neko Project II Kai core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **PC Model (Restart)** [np2kai_model] (**PC-9801VX**/PC-286/PC-9801VM) Awaiting description. - **CPU Base Clock (Restart)** [np2kai_clk_base] (**2.4576 MHz**/1.9968 MHz) Awaiting description. - **CPU Clock Multiplier (Restart)** [np2kai_clk_mult] (**4**/5/6/8/10/12/16/20/24/30/36/40/42/1/2) Awaiting description. - **RAM Size (Restart)* [np2kai_ExMemory] (**3**/7/11/13/16/32/64/120/230/1) Awaiting description. - **GDC** [np2kai_gdc] (**uPD7220**/uPD72020) Awaiting description. - **Skipline Revisions** [np2kai_skipline] (**Full 255 lines**/ON/OFF) Awaiting description. - **Real Palettes** [np2kai_realpal] (**OFF**/ON) Awaiting description. - **LCD** [np2kai_lcd ] (**OFF**/ON) Awaiting description. - **Sound Board (Restart)** [np2kai_SNDboard] (**PC9801-86**/PC9801-26K + 86/PC9801-86 + Chibi-oto/PC9801-118/PC9801-86 + Mate-X PCM(B460)/Mate-X PCM(B460)/Chibi-oto/Speak Board/Spark Board/Sound Orchestra/Sound Orchestra-V/Sound Blaster 16/AMD-98/Otomi-chanx2/Otomi-chanx2 + 86/None/PC9801-14/PC9801-26K) 26K: for old games. 86: for newer games. - **JastSound** [np2kai_jast_snd] (**OFF**/ON) Awaiting description. - **Sound Generator** [np2kai_usefmgen] (**fmgen**/Default) Awaiting description. - **Volume FM** [np2kai_volume_F] (0 to 128 in increments of 4. **64 is default**.) Awaiting description. - **Volume SSG** [np2kai_volume_S] (0 to 128 in increments of 4. **64 is default**.) Awaiting description. - **Volume ADPCM** [np2kai_volume_A] (0 to 128 in increments of 4. **64 is default**.) Awaiting description. - **Volume PCM** [np2kai_volume_P] (0 to 128 in increments of 4. **64 is default**.) Awaiting description. - **Volume RHYTHM** [np2kai_volume_R] (0 to 128 in increments of 4. **64 is default**.) Awaiting description. - **Volume CD-DA** [np2kai_volume_C] (0 to 255 in increments of 8. **128 is default**.) Awaiting description. - **Floppy Seek Sound** [np2kai_Seek_Snd] (**OFF**/ON) Awaiting description. - **Volume Floppy Seek** [np2kai_Seek_Vol] (0 to 128 in increments of 4. **80 is default**.) Awaiting description. - **Volume Beep** [np2kai_BEEP_vol] (**3**/0/1/2) Awaiting description. - **Joypad to Mouse Mapping** [np2kai_joy2mouse] (**OFF**/ON) Awaiting description. - **Joypad to Keyboard Mapping** [np2kai_joy2key] (**OFF**/Arrows/Keypad) Awaiting description. ## Controllers The Neko Project II Kai core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. - **RetroPad** - Joypad - RetroPad w/Analog - Joypad - There's no reason to switch to this. ### Controller tables #### Joypad !!! attention The Joy2Key and Joy2Mouse modes can be activated with the 'Joypad to Mouse Mapping' and 'Joypad to Keyboard Mapping' core options. | RetroPad Inputs | Joy2Key (Arrows) | Joy2Key (Keypad) | Joy2Mouse | |----------------------------------------------|------------------|----------------------------|----------------------| | ![](../image/retropad/retro_b.png) | Z key | Z key | Mouse left button | | ![](../image/retropad/retro_y.png) | Left control key | Left control key | | | ![](../image/retropad/retro_select.png) | Escape key | Escape key | | | ![](../image/retropad/retro_start.png) | Return key | Return key | | | ![](../image/retropad/retro_dpad_up.png) | Up arrow key | Keypad Up arrow key (8) | Move mouse up | | ![](../image/retropad/retro_dpad_down.png) | Down arrow key | Keypad down arrow key (2) | Move mouse down | | ![](../image/retropad/retro_dpad_left.png) | Left arrow key | Keypad left arrow key (4) | Move mouse left | | ![](../image/retropad/retro_dpad_right.png) | Right arrow key | Keypad right arrow key (6) | Move mouse right | | ![](../image/retropad/retro_a.png) | X key | X key | Mouse right button | | ![](../image/retropad/retro_x.png) | Space key | Space key | | | ![](../image/retropad/retro_l1.png) | Backspace key | Backspace key | Increase mouse speed | | ![](../image/retropad/retro_r1.png) | Right shift key | Right shift key | | | ![](../image/retropad/retro_l2.png) | NP2 menu key | NP2 menu key | NP2 menu key | #### Keyboard | RetroKeyboard Inputs | NP2 Keyboard Inputs | |------------------------------|------------------------------------| | Keyboard Backspace | NKEY_BACKSPACE | | Keyboard Tab | NKEY_TAB | | Keyboard Return | NKEY_RETURN | | Keyboard Pause | NKEY_STOP | | Keyboard Escape | NKEY_ESC | | Keyboard Space | NKEY_SPACE | | Keyboard Quote ' | NKEY_COLON | | Keyboard Comma , | NKEY_COMMA | | Keyboard Minus - | NKEY_MINUS | | Keyboard Period . | NKEY_DOT | | Keyboard Slash / | NKEY_SLASH | | Keyboard 0 | NKEY_0 | | Keyboard 1 | NKEY_1 | | Keyboard 2 | NKEY_2 | | Keyboard 3 | NKEY_3 | | Keyboard 4 | NKEY_4 | | Keyboard 5 | NKEY_5 | | Keyboard 6 | NKEY_6 | | Keyboard 7 | NKEY_7 | | Keyboard 8 | NKEY_8 | | Keyboard 9 | NKEY_9 | | Keyboard Colon : | NKEY_COLON | | Keyboard Semicolon ; | NKEY_SEMICOLON | | Keyboard Equals = | NKEY_CIRCUMFLEX | | Keyboard At @ | NKEY_ATMARK | | Keyboard Left Bracket [ | NKEY_LEFTSBRACKET | | Keyboard Backslash \ | NKEY_YEN | | Keyboard Right Bracket ] | NKEY_RIGHTSBRACKET | | Keyboard Caret ^ | NKEY_CIRCUMFLEX | | Keyboard Underscore _ | NKEY_UNDERSCORE | | Keyboard Backquote ` | NKEY_ATMARK | | Keyboard a | NKEY_A | | Keyboard b | NKEY_B | | Keyboard c | NKEY_C | | Keyboard d | NKEY_D | | Keyboard e | NKEY_E | | Keyboard f | NKEY_F | | Keyboard g | NKEY_G | | Keyboard h | NKEY_H | | Keyboard i | NKEY_I | | Keyboard j | NKEY_J | | Keyboard k | NKEY_K | | Keyboard l | NKEY_L | | Keyboard m | NKEY_M | | Keyboard n | NKEY_N | | Keyboard o | NKEY_O | | Keyboard p | NKEY_P | | Keyboard q | NKEY_Q | | Keyboard r | NKEY_R | | Keyboard s | NKEY_S | | Keyboard t | NKEY_T | | Keyboard u | NKEY_U | | Keyboard v | NKEY_V | | Keyboard w | NKEY_W | | Keyboard x | NKEY_X | | Keyboard y | NKEY_Q | | Keyboard z | NKEY_Z | | Keyboard Delete | NKEY_DEL | | Keyboard Keypad 0 | NKEY_KP_0 | | Keyboard Keypad 1 | NKEY_KP_1 | | Keyboard Keypad 2 | NKEY_KP_2 | | Keyboard Keypad 3 | NKEY_KP_2 | | Keyboard Keypad 4 | NKEY_KP_4 | | Keyboard Keypad 5 | NKEY_KP_5 | | Keyboard Keypad 6 | NKEY_KP_6 | | Keyboard Keypad 7 | NKEY_KP_7 | | Keyboard Keypad 8 | NKEY_KP_8 | | Keyboard Keypad 9 | NKEY_KP_9 | | Keyboard Keypad Period . | NKEY_KP_DOT | | Keyboard Keypad Divide / | NKEY_KP_SLASH | | Keyboard Keypad Multiply * | NKEY_KP_ASTERISK | | Keyboard Keypad Minus - | NKEY_KP_MINUS | | Keyboard Keypad Plus + | NKEY_KP_PLUS | | Keyboard Keypad Enter | NKEY_RETURN | | Keyboard Keypad Equals = | NKEY_KP_EQUAL | | Keyboard Up | NKEY_UP | | Keyboard Down | NKEY_DOWN | | Keyboard Right | NKEY_RIGHT | | Keyboard Left | NKEY_LEFT | | Keyboard Insert | NKEY_INS | | Keyboard Home | NKEY_HOMECLR | | Keyboard End | NKEY_HELP | | Keyboard Page Up | NKEY_ROLLUP | | Keyboard Page Down | NKEY_ROLLDOWN | | Keyboard F1 | NKEY_F1 | | Keyboard F2 | NKEY_F2 | | Keyboard F3 | NKEY_F3 | | Keyboard F4 | NKEY_F4 | | Keyboard F5 | NKEY_F5 | | Keyboard F6 | NKEY_F6 | | Keyboard F7 | NKEY_F7 | | Keyboard F8 | NKEY_F8 | | Keyboard F9 | NKEY_F9 | | Keyboard F10 | NKEY_F10 | | Keyboard F11 | Mouse capture (hidden/show toggle) | | Keyboard F12 | NP2 menu key | | Keyboard Caps Lock | NKEY_CAPS | | Keyboard Right Shift | NKEY_SHIFT | | Keyboard Left Shift | NKEY_SHIFT | | Keyboard Right Control | NKEY_CTRL | | Keyboard Left Control | NKEY_CTRL | | Keyboard Right Alt | NKEY_KANA | | Keyboard Left Alt | NKEY_KANA | | Keyboard Print | NKEY_COPY | Supported combinations - If you use 104 western keyboard, to input underscore(_), press Shift+right Ctrl. #### Mouse | RetroMouse Inputs | NP2 Mouse Inputs | |-----------------------------------------------------|--------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | Mouse Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | Mouse Right Button | | ![](../image/retromouse/retro_middle.png) Mouse 3 | NP2 menu key | ## Compatibility Awaiting description. ## External Links - [Official Neko Project II Kai Website](http://domisan.sakura.ne.jp/article/np2kai/np2kai.html) - [Original Neko Project II Website](http://www.yui.ne.jp/np2/) - [Libretro Neko Project II Kai Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/np2kai_libretro.info) - [Libretro Neko Project II Kai Repository](https://github.com/AZO234/NP2kai) - [Report Libretro Neko Project II Kai Core Issues Here](https://github.com/AZO234/NP2kai/issues) ================================================ FILE: docs/library/nestopia.md ================================================ # Nintendo - NES / Famicom (Nestopia) ## Background Nestopia is a cycle accurate emulator for the NES/Famicom. This is the libretro port of the Nestopia emulator, based on the de facto upstream Nestopia JG fork. The libretro port contains an additional overclocking feature. ### Author/License The Nestopia core has been authored by - Martin Freij - R. Danbrook - [Rupert Carmichael (carmiker)](https://github.com/carmiker) The Nestopia core is licensed under - [GPLv2](https://github.com/libretro/nestopia/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the Nestopia core have the following file extensions: - .nes - .fds - .unf - .unif ## Databases RetroArch database(s) that are associated with the Nestopia core: - [Nintendo - Nintendo Entertainment System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%20Entertainment%20System.rdb) - [Nintendo - Family Computer Disk System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Family%20Computer%20Disk%20System.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. !!! warning Prior to version 1.50, it required the [NstDatabase.xml](#nstdatabasexml) file for general proper emulation. In version 1.50 or higher, it's baked into the core. | Filename | Description | md5sum | |:---------------:|:-----------------------------------------------------------------------------:|:--------------------------------:| | disksys.rom | Family Computer Disk System BIOS - Required for Famicom Disk System emulation | ca30b50f880eb660a320674ed365ef7a | ## Features Frontend-level settings or features that the Nestopia core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Nestopia core's internal core name is 'Nestopia' The Nestopia core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.srm (Cartridge battery save) **Frontend's State directory** - 'content-name'.state# (State) **Frontend's System directory** - custom.pal (Custom palette file) ### Geometry and timing - The Nestopia core's core provided FPS is (FPS) - The Nestopia core's core provided sample rate is 44100 Hz - The Nestopia core's core provided aspect ratio is dependent on the ['Preferred aspect ratio' core option](#core-options). ### NstDatabase.xml The Nestopia core relies on the internal database (built from the NstDatabase.xml file) for - Games that support a custom mapper - Games that support multitap accessories - Games that support the Zapper - ROM Hacks - Famicom Disk System games - General proper emulation of games ### Custom color palettes To use custom color palettes in the Nestopia core, the custom color palette file you want to use must be in RetroArch's system directory. Make sure the custom palette file is named 'custom.pal' Also, the 'Palette' core option must be set to custom. Custom color palettes for the NES can be generated with either of these tools. - [Bisqwit's NTSC NES palette generator](http://bisqwit.iki.fi/utils/nespalette.php) - [Drag's NTSC NES palette generator](http://drag.wootest.net/misc/palgen.html) ## Core options The Nestopia core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Blargg NTSC filter** [nestopia_blargg_ntsc_filter] (**disabled**|composite|svideo|rgb|monochrome) Enable Blargg NTSC filters. !!! attention "Disclaimer" These 'Blargg NTSC filter' core option screenshots have been taken with the 'Palette' core option set to cxa2025as. ??? note "Blargg NTSC filter - Off" ![](../image/core/nestopia/blargg_off.png) ??? note "Blargg NTSC filter - composite" ![](../image/core/nestopia/blargg_composite.png) ??? note "Blargg NTSC filter - svideo" ![](../image/core/nestopia/blargg_svideo.png) ??? note "Blargg NTSC filter - rgb" ![](../image/core/nestopia/blargg_rgb.png) ??? note "Blargg NTSC filter - monochrome" ![](../image/core/nestopia/blargg_monochrome.png) - **Palette** [nestopia_palette] (**cxa2025as**|consumer|canonical|alternative|rgb|pal|composite-direct-fbx|pvm-style-d93-fbx|ntsc-hardware-fbx|nes-classic-fbx-fs|raw|custom) Choose which color palette is going to be used. !!! attention "Disclaimer" These 'Palette' core option screenshots have been taken with the 'Blargg NTSC filter' core option set to Off. ??? note "Palette - cxa2025as" ![](../image/core/nestopia/cxa2025as.png) ??? note "Palette - consumer" ![](../image/core/nestopia/consumer.png) ??? note "Palette - canonical" ![](../image/core/nestopia/canonical.png) ??? note "Palette - alternative" ![](../image/core/nestopia/alternative.png) ??? note "Palette - rgb" ![](../image/core/nestopia/rgb.png) ??? note "Palette - pal" ![](../image/core/nestopia/pal.png) ??? note "Palette - composite-direct-fbx" ![](../image/core/nestopia/composite_direct_fbx.png) ??? note "Palette - pvm-style-d93-fbx" ![](../image/core/nestopia/pvm_style_d93_fbx.png) ??? note "Palette - ntsc-hardware-fbx" ![](../image/core/nestopia/ntsc_hardware_fbx.png) ??? note "Palette - nes-classic-fbx-fs" ![](../image/core/nestopia/nes_classic_fbx_fs.png) ??? note "Palette - raw" ![](../image/core/nestopia/raw.png) - **Remove Sprite Limit** [nestopia_nospritelimit] (**disabled**|enabled) Remove 8-sprites-per-scanline hardware limit. - **CPU Speed (Overclock)** [nestopia_overclock] (**1x**|2x) Overclock the emulated CPU. - **4 Player Adapter** [nestopia_select_adapter] (**auto**|ntsc|famicom) Manually select a 4 Player Adapter if needed. Some games will not recognize the adapter correctly through the internal database, this option should help fix that. - **FDS Auto Insntert** [nestopia_fds_auto_insert] (**enabled**|disabled) Automatically insert first FDS disk on reset. - **Mask Overscan (Vertical)** [nestopia_overscan_v] (**enabled**|disabled) Mask out (vertically) the potentially random glitchy video output that would have been hidden by the bezel around the edge of a standard-definition television screen. ??? note "Mask Overscan (Vertical) - On" ![](../image/core/nestopia/vert_on.png) ??? note "Mask Overscan (Vertical) - Off" ![](../image/core/nestopia/vert_off.png) - **Mask Overscan (Horizontal)** [nestopia_overscan_h] (**disabled**|enabled) Mask out (horizontally) the potentially random glitchy video output that would have been hidden by the bezel around the edge of a standard-definition television screen. ??? note "Mask Overscan (Horizontal) - Off" ![](../image/core/nestopia/horiz_off.png) ??? note "Mask Overscan (Horizontal) - On" ![](../image/core/nestopia/horiz_on.png) - **Preferred aspect ratio** [nestopia_aspect] (**auto**|ntsc|pal|4:3) Choose the preferred aspect ratio. RetroArch's aspect ratio must be set to Core provided in the Video settings. 'auto' will use the [internal database](#nstdatabasexml) for aspect ratio autodetection. ??? note "Preferred aspect ratio - ntsc" ![](../image/core/nestopia/ratio_ntsc.png) ??? note "Preferred aspect ratio - pal" ![](../image/core/nestopia/ratio_pal.png) ??? note "Preferred aspect ratio - 4:3" ![](../image/core/nestopia/ratio_4by3.png) - **Game Genie Sound Distortion** [nestopia_genie_distortion] (**disabled**|enabled) The Game Genie cheat device could inadvertently introduce sound distortion in games. By enabling this, you can simulate the distortion it would add to a game's sound. - **System Region** [nestopia_favored_system] (**auto**|ntsc|pal|famicom|dendy) Choose which region the system is from. 'auto' will use the internal database for region autodetection. - **RAM Power-on State** [nestopia_ram_power_state] (**0x00**|0xFF|random) Awaiting description. - **Turbo Pulse Speed** [nestopia_turbo_pulse] (**2**|3|4|5|6|7|8|9) Set the turbo pulse speed for the Turbo B and Turbo A buttons. ## Controllers The Nestopia core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 - 4 device types - None - Disables input. - **Auto** - Automatically detects the device to use based on the internal database. - Gamepad - Joypad - Arkanoid - Arkanoid paddle - This should be automatic from the internal database, but this can be changed to Gamepad if you'd prefer using a joypad rather than a paddle. (Port 2 only) - Zapper - Lightgun - The Nestopia core can emulate Zapper inputs. This is generally done automatically based off of the internal database, but can be manually selected as a device type. (Port 2 only) ### Multitap support The Nestopia core uses the internal database to detect which games have multitap support. ### Controller tables #### Joypad ![](../image/controller/nes.png) | User 1 Remap descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Turbo B | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | Turbo A | ![](../image/retropad/retro_x.png) | | (FDS) Disk Side Change | ![](../image/retropad/retro_l1.png) | | (FDS) Eject Disk | ![](../image/retropad/retro_r1.png) | | (VSSystem) Coin 1 | ![](../image/retropad/retro_l2.png) | | (VSSystem) Coin 2 | ![](../image/retropad/retro_r2.png) | | (Famicom) Microphone | ![](../image/retropad/retro_l3.png) | | User 2 - 4 Remap descriptors | RetroPad Inputs | |------------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Turbo B | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | Turbo A | ![](../image/retropad/retro_x.png) | | (FDS) Disk Side Change | ![](../image/retropad/retro_l1.png) | | (FDS) Eject Disk | ![](../image/retropad/retro_r1.png) | #### Lightgun | RetroLightgun Inputs | Zapper | |--------------------------------------------------------|------------------| | ![](../image/retromouse/retro_mouse.png) Gun Crosshair | Zapper Crosshair | | Gun Trigger | Zapper Trigger | | Gun Aux B | Zapper Light On | ## Compatibility The Nestopia core is compatible with 100% of officially released titles, and the vast majority of homebrew and hacks. ## External Links - [Upstream Nestopia JG Repository](https://gitlab.com/jgemu/nestopia) - [Libretro Nestopia Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/nestopia_libretro.info) - [Libretro Nestopia Github Repository](https://github.com/libretro/nestopia) - [Report Libretro Nestopia Core Issues Here](https://github.com/libretro/nestopia/issues) ### See also #### Nintendo - Family Computer Disk System - [Nintendo - NES / Famicom (FCEUmm)](fceumm.md) - [Nintendo - NES / Famicom (Mesen)](mesen.md) #### Nintendo - Nintendo Entertainment System - [Nintendo - NES / Famicom (bnes)](bnes.md) - [Nintendo - NES / Famicom (Emux NES)](emux_nes.md) - [Nintendo - NES / Famicom (FCEUmm)](fceumm.md) - [Nintendo - NES / Famicom (Mesen)](mesen.md) - [Nintendo - NES / Famicom (QuickNES)](quicknes.md) ================================================ FILE: docs/library/nestopia_ue.md ================================================ # Nintendo - NES / Famicom (Nestopia) Click on this link here to get redirected to the Nestopia page. ================================================ FILE: docs/library/nside_balanced.md ================================================ # Nintendo - SNES / Famicom (nSide Balanced) ## Background A fork of higan v106 that reimplements the Balanced profile. ### Author/License The nSide Balanced core has been authored by - hex-usr The nSide Balanced core is licensed under - [GPLv3](https://github.com/hex-usr/nSide/blob/master/gpl-3.0.txt) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the nSide Balanced core have the following file extensions: - .sfc - .smc - .gb - .gbc - .bml - .rom ## Databases RetroArch database(s) that are associated with the nSide Balanced core: - [Nintendo - Super Nintendo Entertainment System](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System%20Hacks.rdb) - [Nintendo - Super Nintendo Entertainment System Hacks](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Super%20Nintendo%20Entertainment%20System%20Hacks.rdb) - [Nintendo - Game Boy](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Game%20Boy.rdb) - [Nintendo - Game Boy Color](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Game%20Boy%20Color.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. !!! attention nSide Balanced uses split ROMS for special chip games. !!! attention Firmware files for SGB emulation need to be in directories called SGB1.sfc and SGB2.sfc in RetroArch's system directory. Look at the [Super GameBoy support section](#super-gameboy-support) for more information. Notable DSP1.mdDSP1B Games: - Super Mario Kart - Pilotwings Notable DSP2 Games: - Dungeon Master Notable DSP3 Games: - SD Gundam GX Notable DSP4 Games: - Top Gear 3000 Notable Cx4 Games: - Mega Man X2 - Mega Man X3 | Filename | Description | md5sum | |:----------------------:|:--------------------------------------:|:--------------------------------:| | dsp1.data.rom | DSP1 co-processor firmware - Optional | 3d81b45fa0c2aa8b852dfb1ece7c0971 | | dsp1.program.rom | DSP1 co-processor firmware - Optional | ae209fbe789fbf11a48aea5ab1197321 | | dsp1b.data.rom | DSP1B co-processor firmware - Optional | 1e3f568634a7d8284020dddc0ae905bc | | dsp1b.program.rom | DSP1B co-processor firmware - Optional | d10f446888e097cbf500f3f663cf4f6d | | dsp2.data.rom | DSP2 co-processor firmware - Optional | e9417e29223b139c3c4b635a2a3b8744 | | dsp2.program.rom | DSP2 co-processor firmware - Optional | aa6e5922a3ed5ded54f24247c11143c5 | | dsp3.data.rom | DSP3 co-processor firmware - Optional | 0a81210c0a940b997dd9843281008ee6 | | dsp3.program.rom | DSP3 co-processor firmware - Optional | d99ca4562818d49cee1f242705bba6f8 | | dsp4.data.rom | DSP4 co-processor firmware - Optional | ee4990879eb68e3cbca239c5bc20303d | | dsp4.program.rom | DSP4 co-processor firmware - Optional | a151023b948b90ffc23a5b594bb6fef2 | | cx4.data.rom | CX4 co-processor firmware - Optional | 037ac4296b6b6a5c47c440188d3c72e3 | | st010.data.rom | ST010 co-processor firmware - Optional | 254d70762b6f59f99c27c395aba7d07d | | st010.program.rom | ST010 co-processor firmware - Optional | 1d70019179a59a566a0bb5d3f2845544 | | st011.data.rom | ST011 co-processor firmware - Optional | 10bd3f4aa949737ab9836512c35bcc29 | | st011.program.rom | ST011 co-processor firmware - Optional | 95222ebf1c0c2990bcf25db43743f032 | | st018.data.rom | ST018 co-processor firmware - Optional | 49c898b60d0f15e90d0ba780dd12f366 | | st018.program.rom | ST018 co-processor firmware - Optional | dda40ccd57390c96e49d30a041f9a9e7 | | SGB1.sfc/sgb1.boot.rom | Super Game Boy BIOS - Optional | | | SGB1.sfc/program.rom | Super Game Boy ROM - Optional | | | SGB2.sfc/sgb2.boot.rom | Super Game Boy 2 BIOS - Optional | | | SGB2.sfc/program.rom | Super Game Boy 2 ROM - Optional | | ## Features Frontend-level settings or features that the nSide Balanced core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | - | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✔ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The nSide Balanced core's internal core name is 'higan (Super Famicom Balanced)' The nSide Balanced core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.srm (Cartridge battery save) **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The nSide Balanced core's core provided FPS is (FPS) - The nSide Balanced core's core provided sample rate is (Rate) - The nSide Balanced core's core provided aspect ratio is (Ratio) ## Super Gameboy Support The nSide Balanced core uses a simplified Super Game Boy routine that makes it much easier to access this feature than with the old v094-based cores. Instead of using the complex, CLI-based 'subsystem' launch commands, it looks for the necessary files in the system/BIOS directory whenever you feed the core a *.gb/c file. To get it working, you'll need one or more Super Game Boy ROMs and the sgb.boot.rom BIOS. **Step 1** Make 2 subdirectories in RetroArch's system directory, one named SGB1.sfc and the other named SGB2.sfc. **Step 2** Copy your original Super Game Boy ROM into the SGB1.sfc directory and then rename it to program.rom. Copy your Super Game Boy 2 ROM into the SGB2.sfc directory and then rename it program.rom, as well. **Step 3** Copy your sgb.boot.rom BIOS into each of your SGB1.sfc and SGB2.sfc directories, and rename them to sgb1.boot.rom and sgb2.boot.rom, respectively. The ['Preferred Super GameBoy BIOS' core option](#core-options) lets you choose which of the two SGB BIOSes to use. **Step 4** Load a SGB-supported GB.mdGBC rom. **Done** ![](../image/core/higan/sgb.png) !!! warning There may be graphical glitches when Rewind is set to On in RetroArch's settings. ## MSU-1 !!! attention MSU-1 support in this core is complex. **Use the [Snes9x core](../library/snes9x#msu-1-support) for simplified and easily accessible MSU-1 support.** MSU-1 support can be used by loading a correct .bml file. There's documentation for loading MSU-1 games in standalone higan [here](https://higan.readthedocs.io/en/stable/guides/import/#msu-1-games). ## Core options The nSide Balanced core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Internal resolution** [higan_sfc_internal_resolution] (**512x480**|512x448|512x240|512x224|256x240|256x224) Self-explanatory. ??? note "512x480" ![](../image/core/higan/512x480.png) ??? note "512x448" ![](../image/core/higan/512x448.png) ??? note "512x240" ![](../image/core/higan/512x240.png) ??? note "512x224" ![](../image/core/higan/512x224.png) ??? note "256x240" ![](../image/core/higan/256x240.png) ??? note "256x224" ![](../image/core/higan/256x224.png) - **Color emulation** [higan_sfc_color_emulation] (**OFF**|ON) Simulates the way a console’s display device differs from modern computer monitor’s colour reproduction. In particular, it simulates the slightly-different gamma correction used by the Super Famicom. ??? note "Color emulation - Disabled" ![](../image/core/higan/color_off.png) ??? note "Color emulation - Enabled" ![](../image/core/higan/color_on.png) - **Blur emulation** [higan_sfc_blur_emulation] (**OFF**|ON) Simulates the limited horizontal resolution of standard-definition TVs by blurring together horizontally-adjacent pixels. Games like Jurassic Park for the Super Famicom depend on this to emulate a transparency effect. ??? note "Blur emulation - Disabled" ![](../image/core/higan/blur_off.png) ??? note "Blur emulation - Enabled" ![](../image/core/higan/blur_on.png) - **Scanline emulation** [higan_sfc_scanline_emulation] (**OFF**|ON) Currently does not function properly. - **Preferred Super GameBoy BIOS (restart)** [higan_sfc_sgb_bios] (**SGB1.sfc/**|SGB2.sfc/) Choose what Super GameBoy BIOS you want to use. Look at the [Super GameBoy Support section](#super-gameboy-support) for more information. ## Controllers The nSide Balanced core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Input disabled. - [**SNES Joypad**](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller) - Joypad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse ### User 2 device types - None - Input disabled. - [**SNES Joypad**](http://nintendo.wikia.com/wiki/Super_Nintendo_Entertainment_System_controller) - Joypad - [SNES Mouse](https://en.wikipedia.org/wiki/Super_NES_Mouse) - Mouse - [Multitap](http://nintendo.wikia.com/wiki/Super_Multitap) - Joypad - Allows for up to five players to play together in multitap games. - [SuperScope](https://en.wikipedia.org/wiki/Super_Scope) - Lightgun - Inputs are not hooked up in this core. - [Justifier](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - Inputs are not hooked up in this core. - [Justifiers](https://en.wikipedia.org/wiki/Konami_Justifier) - Lightgun - Two Justifiers are plugged in, for two-player Justifier games. Inputs are not hooked up in this core. ### Multitap support Activating multitap support in compatible games can be configured by switching to the [Multitap device type](#controllers) for User 2. ### Controller tables #### Joypad ![](../image/controller/snes.png) | User 1 - 5 Remap descriptors | RetroPad Inputs | |------------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Y | ![](../image/retropad/retro_y.png) | | Select | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | A | ![](../image/retropad/retro_a.png) | | X | ![](../image/retropad/retro_x.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | #### Mouse | RetroMouse Inputs | SNES Mouse | |-------------------------------------------------------|---------------------------| | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | SNES Mouse Cursor | | ![](../image/retromouse/retro_left.png) Mouse 1 | SNES Mouse Left Button | | ![](../image/retromouse/retro_right.png) Mouse 2 | SNES Mouse Right Button | ## Compatibility | Game | Issue | |--------------------------|--------------------------------------------------------------------------------| | A.S.P. Air Strike Patrol | Black lines show up during gameplay. The shadow below the aircraft is missing. | Incompatible with ROM hacks made to take advantage of emulator quirks, much like real hardware. ## External Links - [Official higan Website](https://byuu.org/) - [Official higan Upstream Downloads](https://byuu.org/emulation/higan/) - [Libretro nSide Balanced Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/higan_sfc_balanced_libretro.info) - [Libretro nSide Balanced Github Repository](https://github.com/hex-usr/nSide) - [Report Libretro nSide Balanced Core Issues Here](https://github.com/hex-usr/nSide/issues) ### See also #### Nintendo - Game Boy (+ Color) - [Nintendo - Game Boy / Color (Emux GB)](emux_gb.md) - [Nintendo - Game Boy / Color (Gambatte)](gambatte.md) - [Nintendo - Game Boy / Color (Gearboy)](gearboy.md) - [Nintendo - Game Boy / Color (SameBoy)](sameboy.md) - [Nintendo - Game Boy / Color (TGB Dual)](tgb_dual.md) - [Nintendo - Game Boy Advance (mGBA)](mgba.md) - [Nintendo - Game Boy Advance (VBA-M)](vba_m.md) - [Nintendo - SNES / Famicom (higan Accuracy)](higan_accuracy.md) - [Nintendo - SNES / Famicom (Mesen-S)](mesen-s.md) #### Nintendo - Super Nintendo Entertainment System (+ Hacks) - [Nintendo - SNES / Famicom (Beetle bsnes)](beetle_bsnes.md) - [Nintendo - SNES / Famicom (bsnes-mercury Accuracy)](bsnes_mercury_accuracy.md) - [Nintendo - SNES / Famicom (bsnes-mercury Balanced)](bsnes_mercury_balanced.md) - [Nintendo - SNES / Famicom (bsnes-mercury Performance)](bsnes_mercury_performance.md) - [Nintendo - SNES / Famicom (bsnes Accuracy)](bsnes_accuracy.md) - [Nintendo - SNES / Famicom (bsnes Balanced)](bsnes_balanced.md) - [Nintendo - SNES / Famicom (bsnes C++98 (v085))](bsnes_cplusplus98.md) - [Nintendo - SNES / Famicom (bsnes Performance)](bsnes_performance.md) - [Nintendo - SNES / Famicom (higan Accuracy)](higan_accuracy.md) - [Nintendo - SNES / Famicom (Mesen-S)](mesen-s.md) - [Nintendo - SNES / Famicom (Snes9x)](snes9x.md) - [Nintendo - SNES / Famicom (Snes9x 2002)](snes9x_2002.md) - [Nintendo - SNES / Famicom (Snes9x 2005 Plus)](snes9x_2005_plus.md) - [Nintendo - SNES / Famicom (Snes9x 2005)](snes9x_2005.md) - [Nintendo - SNES / Famicom (Snes9x 2010)](snes9x_2010.md) ================================================ FILE: docs/library/numero.md ================================================ # Texas Instruments TI-83 (Numero) ![](../image/core/numero/preview.gif) ## Background Numero is a libretro core for emulating the TI-83 family of graphing calculators. It is based on the awesome Wabbitemu emulator. It allows you to play your TI-83 games like never before in fullscreen and using a gamepad! You can also control it with a mouse or keyboard, or you can just use the virtual mouse for pressing the calculator buttons. The Numero core has been authored by - Neil Barkhina The Numero core is licensed under - [GPLv2](https://github.com/nbarkhina/numero/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS It is required to have one of the bios files below in the frontend's system directory. ti83se.rom is the recommended BIOS as that will give you the largest memory capacity. | Filename | Description | md5sum | |:-----------------:|:-------------------------------:|:--------------------------------:| | ti83se.rom | TI-83 Silver Edition | c6ff8204c5c81b7be34614dbbd690c8b | | ti83plus.rom | TI-83 Plus | 8011181f810b5ec4e9d6a03f0e14257a | | ti83.rom | TI-83 | d4448d09bbfde687c04f9e3310e023ab | ## Extensions Content that can be loaded by the Numero core have the following file extensions: - .8xp - .8xk - .8xg ## Features Frontend-level settings or features that the Numero core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Directories The Numero core saves/loads to/from the default frontend's save directory. **Frontend's Save directory** | File | Description | |:------------:|:-----------:| | tisavestateprogressti83se.sav | SE Progress Save | | tisavestateprogressti83plus.sav | Plus Progress Save | | tisavestateprogressti83.sav | TI-83 Progress Save | | tisavestatetemp.sav | Temp file used during manual save states | ## Geometry and timing - The Numero core's core provided FPS is 60 - The Numero core's core provided sample rate is 0 (currently no sound) - The Numero core's base width is 640 - The Numero core's base height is 480 - The Numero core's max width is 640 - The Numero core's max height is 480 - The Numero core's core provided aspect ratio is 3/4 ## Usage - The Emulator will save your progress every 10 seconds - this is done in the background since the calculator doesn't really have any "long term storage" - everything was always just saved in RAM - or if you just select "Close Content" in RetroArch that will also immediately save your progress - You can run the core without any content by just selecting "Start Core" - There are two control schemes - Joypad which is the default - And "Gaming Buttons" which is more suited towards gaming - You can move the virtual mouse with the left stick - and by Pressing R2 to click - You can also use the D-Pad and A Button if using the Joypad scheme - Change the virtual mouse speed in the core Options - You can toggle between the calculator view and "Big Mode" with L2 - Hitting "Restart" in the RetroArch menu will clear the entire memory - So be careful when doing this because you will lose all your data - This is useful however sometimes when the emulator hangs for one reason or another - Installing Apps - You will probably need to install some "loaders" for most of the demanding apps - Such as "Ion" or "Mirage" - You can install "Ion.8xg" by going to Retroarch => Load Content - After starting you will see a message in the bottom left corner if it imported successfully - Then go to "Close Content" - Then go again to "Load Content" and install the game you want to run inside of Ion such as "Ztetris.8xp" - Then keep repeating the process to load all the apps you want (careful not to fill up the entire space) - Essentially you have to load each piece one on top of another since there is a single common "hard drive" for the calculator - Every time you load the emulator you will start from the last place you left off - For the same reason mentioned above where it saves in the background - Also keep this in mind for save states - Save States - You can create as many save states as you want using the different slots - However they will be named internally based on how you started the emulator - From a rom or just the core itself - There will will be a common "In Progress" storage mechanism when loading different states - Save States will restore whatever the state was of the entire calculator - Including all installed apps at the time of saving - Take lots of save states since you may run into problems where you will need to wipe the memory and try again - If you have trouble installing one game or another - Try moving things around between Memory and Archive - Sometimes different launchers require things not be in Archive - You can watch this awesome video by LGR where he talks about the phenomenon - https://www.youtube.com/watch?v=nduMTX86Zl0 ## Core options The Numero core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. - **Speed of virtual mouse** [mouse_speed] (**1x**|2x|3x|4x|5x) ## device types The Numero core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): - None - Doesn't disable input. - **RetroPad** - Joypad - **Gaming Buttons** - Same as joypad but optimized mappings for playing games. Regardless of what you pick the core also supports using the Mouse/Touch to click the calculator buttons. ## Joypad | RetroPad Inputs | User 1 input descriptors | |------------------------------------------------|--------------------------| | ![](../image/retropad/retro_b.png) | Button 2ND | | ![](../image/retropad/retro_y.png) | Button DOWN | | ![](../image/retropad/retro_select.png) | Button ALPHA | | ![](../image/retropad/retro_start.png) | Button ENTER | | ![](../image/retropad/retro_dpad_up.png) | Mouse Up | | ![](../image/retropad/retro_dpad_down.png) | Mouse Down | | ![](../image/retropad/retro_dpad_left.png) | Mouse Left | | ![](../image/retropad/retro_dpad_right.png) | Mouse Right | | ![](../image/retropad/retro_a.png) | Mouse Press | | ![](../image/retropad/retro_x.png) | Button UP | | ![](../image/retropad/retro_l1.png) | Button LEFT | | ![](../image/retropad/retro_r1.png) | Button RIGHT | | ![](../image/retropad/retro_l2.png) | Toggle Big Mode | | ![](../image/retropad/retro_r2.png) | Mouse Press | ## External Links - [Official Numero Github Repository](https://github.com/nbarkhina/numero) - [Libretro Numero Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/numero_libretro.info) - [Report Numero Core Issues Here](https://github.com/nbarkhina/numero/issues) ================================================ FILE: docs/library/nxengine.md ================================================ # Cave Story (NXEngine) ## Background NXEngine is a open source reproduction of the [Cave Story game engine](https://en.wikipedia.org/wiki/Cave_Story). The NXEngine core has been authored by - Caitlin Shaw The NXEngine core is licensed under - [GPLv3](https://github.com/gameblabla/nxengine-nspire/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## How to start the NXEngine core: - To start the NXEngine core, you need to obtain NXEngine's data files. You can do this by going to RetroArch's main menu screen and selecting 'Online Updater'. From there, select 'Content Downloader'.
![](../image/core/all/download.png)
- Select 'NXEngine'', then select 'Cave Story (En).zip'. This should download and extract this file to RetroArch's Downloads directory.
![](../image/core/nxengine/down_story.png)
- Go back to RetroArch's main menu screen. Select 'Load Content', then 'Downloads'.
![](../image/core/all/load.png)
![](../image/core/all/downloads.png)
- Select the 'Cave Story (en)' directory, then select 'Doukutsu.exe'. - If you are asked which core to select, choose 'Cave Story (NXEngine)'. The content should now start running! ## Extensions Content that can be loaded by the NXEngine core have the following file extensions: - .exe ## Databases RetroArch database(s) that are associated with the NXEngine core: - [Cave Story](https://github.com/libretro/libretro-database/blob/master/rdb/Cave%20Story.rdb) ## Features Frontend-level settings or features that the NXEngine core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The NXEngine core's directory name is 'NXEngine' The NXEngine core saves/loads to/from these directories. **Frontend's Save directory** - profile#.dat (Save data profile) ### Geometry and timing - The NXEngine core's core provided FPS is 60 - The NXEngine core's core provided FPS is 22050 Hz - The NXEngine core's core provided aspect ratio is 4/3 ## Controllers The NXEngine core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input - **RetroPad** - Joypad - RetroPad w/Analog - Joypad - There is no reason to switch to this. ### Controller tables #### Joypad | User 1 Remap descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | Jump | ![](../image/retropad/retro_b.png) | | Settings | ![](../image/retropad/retro_select.png) | | Inventory | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | Fire | ![](../image/retropad/retro_a.png) | | Show/Hide Map | ![](../image/retropad/retro_x.png) | | Previous Weapon | ![](../image/retropad/retro_l1.png) | | Next Weapon | ![](../image/retropad/retro_r1.png) | ## External Links - [Official NXEngine Website](http://nxengine.sourceforge.net/) - [Official NXEngine Github Repository](https://github.com/EXL/NXEngine) - [Libretro NXEngine Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/nxengine_libretro.info) - [Libretro NXEngine Github Repository](https://github.com/libretro/nxengine-libretro) - [Report Libretro NXEngine Core Issues Here](https://github.com/libretro/nxengine-libretro/issues) ## (Related cores) - [doukutsu-rs](doukutsu-rs.md) ================================================ FILE: docs/library/o2em.md ================================================ # Magnavox - Odyssey2 / Philips Videopac+ (O2EM) ## Background O2EM is an open source multi-platform Odyssey2 / Videopac+ emulator. The Odyssey2 (Videopac/Jopac in Europe) was a video game console created in the late 70s. The O2EM core has been authored by - Daniel Boris - Andre de la Rocha - Arlindo M. de Oliveira The O2EM core is licensed under - [Artistic License](https://sourceforge.net/projects/o2em/) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:----------:|:------------------------------------------------:|:--------------------------------:| | o2rom.bin | Odyssey2 BIOS - G7000 model - Required | 562d5ebf9e030a40d6fabfc2f33139fd | | c52.bin | Videopac+ French BIOS - G7000 model - Required | f1071cdb0b6b10dde94d3bc8a6146387 | | g7400.bin | Videopac+ European BIOS - G7400 model - Required | c500ff71236068e0dc0d0603d265ae76 | | jopac.bin | Videopac+ French BIOS - G7400 model - Required | 279008e4a0db2dc5f1c048853b033828 | Currently the libretro core only works with the o2rom.bin. As a workaround for playing Videopac+ games, you can rename the g7400.bin firmware file into o2rom.bin, and the core plays it correctly as a Videopac+ game. ## Extensions Content that can be loaded by the O2EM core have the following file extensions: - .bin RetroArch database(s) that are associated with the O2EM core: - [Magnavox - Odyssey2](https://github.com/libretro/libretro-database/blob/master/rdb/Magnavox%20-%20Odyssey2.rdb) - [Philips - Videopac+](https://github.com/libretro/libretro-database/blob/master/rdb/Philips%20-%20Videopac%2B.rdb) ## Features Frontend-level settings or features that the O2EM core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✕ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Directories The O2EM core's library name is 'O2EM' The O2EM core saves/loads to/from these directories. **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ## Geometry and timing - The O2EM core's core provided FPS is 60 for NTSC games and 50 for PAL games - The O2EM core's core provided sample rate is 44100 Hz - The O2EM core's base width is 340 - The O2EM core's base height is 250 - The O2EM core's max width is 340 - The O2EM core's max height is 250 - The O2EM core's core provided aspect ratio is 4/3 ## Core options The O2EM core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. - **Emulated Hardware (Restart)** [o2em_bios] (**o2rom.bin**|Videopac G7000 (European)|Videopac+ G7400 (European)|Videopac+ G7400 (French)) Specify which console hardware to emulate. Requires the corresponding bios file to be present in the frontend 'system' directory (o2rom.bin, c52.bin, g7400.bin, jopac.bin) - **Console Region (Restart)** [o2em_region] (**Auto**|NTSC|PAL) Specify which region the system is from. 'Auto' chooses the correct region based on emulated hardware. 'NTSC' is 60hz, 'PAL' is 50hz. Games may run abnormally if the wrong region is selected, and the setting my be overridden if the current content is incompatible. - **Swap Gamepads** [o2em_swap_gamepads] (**disabled**|enabled) Swap inputs from the two connected controllers of the emulated console. Required for games such as UFO and P.T. Barnum's Acrobats, which accept player 1 input from the second controller. - **Virtual keyboard transparency** [o2em_vkb_transparency] (**0%**|25%|50%|75%) Set transparency level of the virtual on-screen keyboard. ??? note "Virtual keyboard transparency - 0%" ![](../image/core/o2em/0.png) ??? note "Virtual keyboard transparency - 25%" ![](../image/core/o2em/25.png) ??? note "Virtual keyboard transparency - 50%" ![](../image/core/o2em/50.png) ??? note "Virtual keyboard transparency - 75%" ![](../image/core/o2em/0.png) - **Crop Overscan** [o2em_crop_overscan] (**disabled**|enabled) Remove the border around the edges of the screen, typically unused by games and hidden by the bezel of a standard-definition television. - **Interframe Blending** [o2em_mix_frames] (**Simple**|Ghosting (65%)|Ghosting (75%)|Ghosting (85%)|Ghosting (95%)) Simulate CRT phosphor ghosting effects. 'Simple' performs a 50:50 mix of the current and previous frames. 'Ghosting' accumulates pixels from multiple successive frames. May be used to alleviate screen flicker. - **Audio Volume** [o2em_audio_volume] (**50%**|0%)|5%)|10%)|15%|20%|25%|30%|35%|40%|45%|50%|55%|60%|65%|70%|75%|80%|85%|90%|95%|100%) Set output audio volume level. - **Voice Volume** [o2em_voice_volume] (**70%**|0%)|5%)|10%)|15%|20%|25%|30%|35%|40%|45%|50%|55%|60%|65%|70%|75%|80%|85%|90%|95%|100%) Set output volume level of 'The Voice' speech samples. The voice sampleset WAV files must be placed in the frontend 'system/voice' directory. - **Audio Filter** [o2em_low_pass_filter] (**disabled**|enabled) Apply a low pass audio filter to soften the 'harsh' sound effects produced by most Odyssey2/Videopac+ games. - **Audio Filter Level** [o2em_low_pass_range] (**60%**|0%)|5%)|10%)|15%|20%|25%|30%|35%|40%|45%|50%|55%|60%|65%|70%|75%|80%|85%|90%|95%|100%) Specify the cut-off frequency of the low pass audio filter. A higher value increases the perceived 'strength' of the filter, since a wider range of the high frequency spectrum is attenuated. ## Joypad | RetroPad Inputs | User 1 input descriptors | |----------------------------------------------|--------------------------| | ![](../image/retropad/retro_dpad_up.png) | Up | | ![](../image/retropad/retro_dpad_down.png) | Down | | ![](../image/retropad/retro_dpad_left.png) | Left | | ![](../image/retropad/retro_dpad_right.png) | Right | | ![](../image/retropad/retro_b.png) | Action / Press Key (Virtual Keyboard) | | ![](../image/retropad/retro_y.png) | Move Virtual Keyboard Up/Down | | ![](../image/retropad/retro_select.png) | Show/Hide Virtual Keyboard | | RetroPad Inputs | User 2 input descriptors | |----------------------------------------------|--------------------------| | ![](../image/retropad/retro_dpad_up.png) | Up | | ![](../image/retropad/retro_dpad_down.png) | Down | | ![](../image/retropad/retro_dpad_left.png) | Left | | ![](../image/retropad/retro_dpad_right.png) | Right | | ![](../image/retropad/retro_b.png) | Action | In some games, for example UFO/Satellite Attack, the original had the joypads swapped so that Player 1 was on Joypad 2. If you only use one Joypad, a workaround is to provide identical assignments of both Retropads to one joystick and save it as Game Remap or Core Remap. ## Keyboard | RetroKeyboard Inputs | O2EM Inputs | |------------------------------|-------------| | Keyboard Return | Enter | | Keyboard Space | Space | | Keyboard Minus - | - | | Keyboard Period . | . | | Keyboard Slash / | / | | Keyboard 0 | 0 | | Keyboard 1 | 1 | | Keyboard 2 | 2 | | Keyboard 3 | 3 | | Keyboard 4 | 4 | | Keyboard 5 | 5 | | Keyboard 6 | 6 | | Keyboard 7 | 7 | | Keyboard 8 | 8 | | Keyboard 9 | 9 | | Keyboard Equals = | = | | Keyboard Question ? | ? | | Keyboard a | a | | Keyboard b | b | | Keyboard c | c | | Keyboard d | d | | Keyboard e | e | | Keyboard f | f | | Keyboard g | g | | Keyboard h | h | | Keyboard i | i | | Keyboard j | j | | Keyboard k | k | | Keyboard l | l | | Keyboard m | m | | Keyboard n | n | | Keyboard o | o | | Keyboard p | p | | Keyboard q | q | | Keyboard r | r | | Keyboard s | s | | Keyboard t | t | | Keyboard u | u | | Keyboard v | v | | Keyboard w | w | | Keyboard x | x | | Keyboard y | y | | Keyboard z | z | | Keyboard End | Clear | ## External Links - [Official O2EM Website](http://o2em.sourceforge.net/) - [Official O2EM SourceForge Repository](https://sourceforge.net/projects/o2em/) - [Libretro O2EM Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/o2em_libretro.info) - [Libretro O2EM Github Repository](https://github.com/libretro/libretro-o2em) - [Report Libretro O2EM Core Issues Here](https://github.com/libretro/libretro-o2em/issues) - [Gameplay Videos](https://youtube.com/playlist?list=PLRbgg4gk_0IdZx5HP3o3h8iNkzOx8l4Dn) ================================================ FILE: docs/library/openlara.md ================================================ # Tomb Raider (OpenLara) ==First, make sure these steps are permissible in your locale. RetroArch and LibRetro do not share any copyrighted content.== ## Background A new work-in-progress Tomb Raider game engine ported to libretro. This game engine recreation seeks to allow you to play the original Tomb Raider engine games, from 1 all the way up to 5. OpenLara V1 Tomb Raider 1 is fully playable. The nice thing about OpenLara is that, while staying true to the original look and feel of the original, it also adds some enhancements to it that manages to make the boxy old-school Tomb Raider games look a bit less archaic. Some examples include : - The framerate is no longer fixed to 30fps, and you can now run it at a smooth 60fps framerate. There are even more framerate options, allowing you to play at 90fps, 120fps or even 144fps. - You can set the internal resolution of the game. - New water effects which replaces the simple vertex manipulation of the water surface on the PSX. The Saturn version actually was the only version that tried to do something a bit more sophisticated with the water. - Self-shadowing on all the player models (although this still has some visual anomalies at places). - Improved lighting effects, including colored lighting (you can see the save crystals emanating a blue light for instance, something which definitely was not in any of the prior Tomb Raider versions). - Shading effects – after Lara gets out of the water, her skin has a slightly wet shading effect. - There is also a brand new local multiplayer mode. You toggle the game into splitscreen mode by pressing Start at any one time. From there, you can see a second Lara character, which is only distinguished from the main character by a slightly jerky animation update routine. Player 2 can now take control of this Lara and you can engage in ‘jolly co-operation’. At all times, Player 1 can beckon Player 2 back to his position by pressing the Start button, which resets player 2’s position back to Player 1’s so that Player 2 can always be brought back in case he/she is running too far astray. - There is also a first person view that you can toggle into by pressing the Look button (L button) and then pressing the Action button (B button). This gives you a Mirror’s Edge-esque first person view. - The ability to target two enemies at the same time individually. - The graphical enhancements can all be toggled on/off inside the game’s inventory settings screen (toggleable by pressing the Select button). The OpenLara core has been authored by - XProger The OpenLara core is licensed under - [2-clause BSD](https://github.com/XProger/OpenLara/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Requirements This core requires that you use OpenGL as the video driver. Go to Settings -> Driver. If ‘video driver’ is set to ‘vulkan’, switch it back to ‘gl’, and then restart. ![](../image/core/openlara/gl.png) !!! attention There is currently no ‘working’ macOS version available due to the OpenGL requirement. ## Extensions Content that can be loaded by the OpenLara core have the following file extensions: - .phd - .psx - .tr2 RetroArch dat that is associated with the OpenLara core: - [Tomb Raider](https://raw.githubusercontent.com/libretro/libretro-database/master/dat/Tomb%20Raider.dat) ## Setup TR1 is officially supported while 2 or 3 is not. You can still load the levels of 2 or 3 and play them with the proper file scheme. You can download the demo from Online Updater > Content Downloader > Tomb Raider and test Level 2. You can also experience the OpenLara's features in the demo. Apart from that, you can buy it [here on GOG](https://www.gog.com/game/tomb_raider_123) or [here on Steam](https://store.steampowered.com/app/224960/Tomb_Raider_I/). Tomb Raider has differences between ports. The Steam and GOG version do not install the DATA and FMV folders directly into the directory. In Console versions, these files are in the image file. ### Files - DATA, with .phd and .pcx files inside. These are the level files and title screen textures. - FMV, which contains a couple of .rpl files. These are the movies. Not all audio files are available in the Steam/GOG distribution. In this case, you cannot hear some audio streams. For example, in the GYM level, you cannot hear Lara's instructions, but you can hear the sounds of walking, jumping and taking damage. ## Getting Tomb Raider files First, make sure these steps are permissible in your locale RetroArch or LibRetro do not share copyrighted content. ### Rip Tomb Raider 1 Image from Steam/GOG When you get Tomb Raider on digital platforms, you will see *GAME.GOG*(game file), *GAME.DAT*, dosbox.exe and configuration file of dosbox inside the folder. ??? note "Files inside Tomb Raider 1 from Steam" ![RetroArch and LibRetro do not share any copyrighted content.](../image/core/openlara/files.png) GOG files store audio samples in Drumagog format. This format was developed by WaveMachine Labs for a software plugin that offers access to acoustic drums samples. GOG files are associated with VST technology and are compatible with any software that supports it. GOG format was originally developed in 1999 and is regularly updated. Open the **dosbox.conf** file with a text editing file. Scroll down to until **[autoexec]**, lines in this section will be run at startup. ``` mount C . imgmount d ".\game.dat" -t iso -fs iso xcopy D:\DATA\ C:\DATA\ xcopy D:\FMV\ C:\FMV\ ``` When you paste the code above, **dosbox.exe** will boot the image and copy the **DATA** and **FMV** files in it to the local machine each time it is opened. The computer version does not contain most audio files. For example, when you export existing audio files, you cannot hear Lara's instructions at the GYM level. ??? note "Folders from Tomb Raider 1 image" ![RetroArch and LibRetro do not share any copyrighted content.](../image/core/openlara/steam-folder.png) You must convert the audio files in the main folder of TR1 to .ogg format. You can do this with the small [FFmpeg](https://github.com/FFmpeg/FFmpeg) script below. Apart from that, you can use console audio files with PC port. ??? note "Converting to OGG" ``` for f in ./*.mp3; do ffmpeg -i "$f" -c:a libvorbis -q:a 4 "${f/%mp3/ogg}"; done ``` This will convert files from mp3 to ogg The PC Port also missing title and loading images, you can get them from the console version. Place the **DELDATA** folder from the Console port into the main TR1 directory. ??? note "Missing Title Screen / Title Screen from Console" ![Missing Title Screen](../image/core/openlara/missing-title-screen.png) ![Title Screen from Console](../image/core/openlara/title-screen-from-console.png) ### Rip Tomb Raider 1 Image from Console [jPSXdec](https://github.com/m35/jpsxdec) is a modern, cross-platform PlayStation 1 audio/video converter. Check their documentation to understand how to use it. ## Folder Setup To achieve a continuous game that loads from one level to the next you can load directly from CD or preferably setup the content folder like this: | Folder | File Type(s) | Description | |:--------:|:----------------------------------------:|:---------------------------------------:| | audio/1/ | track_XX.ogg or XXX.ogg | X represents a number | | audio/2/ | track_XX.ogg and MAIN.SFX | Both tracks and MAIN.SFX are required | | audio/3/ | track_XX.ogg and MAIN.SFX | Both tracks and MAIN.SFX are required | | level/1/ | *.PNG and *.PHD or *.PSX or *.SAT | Load-screens and levels | | level/2/ | *.PNG and *.TR2 or *.PSX | Load-screens and levels | | level/3/ | *.PNG and *.TR2 or *.PSX | Load-screens and levels | | video/1/ | *.RPL or *.FMV | Video cut-scenes | | video/2/ | *.RPL or *.FMV | Video cut-scenes | | video/3/ | *.RPL or *.FMV | Video cut-scenes | !!! note if you load from CD you won't have soundtrack in TR1 ## Features Frontend-level settings or features that the OpenLara core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✕ | | Saves | ✔ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### FPS mode With OpenLara, you can experience Tomb Raider like you've never played before. You can try it through the eyes of Lara Croft with the primary person camera, for this you can switch to this mode by pressing L1 + A and exit this mode with the same combination. FPS also available in 2-Player Mode. ??? note "FPS mode" ![RetroArch and LibRetro do not share any copyrighted content.](../image/core/openlara/fps.png) ### 2-Player Mode You can include your friend with whom you want to pass TR levels together. Press Start from Second Controller in order to go 2-Payer Mode. ??? note "2-Player Mode" ![RetroArch and LibRetro do not share any copyrighted content.](../image/core/openlara/2-player-mode.png) ## Directories The OpenLara core's library name is 'OpenLara' The OpenLara core saves/loads to/from these directories. | File | Description | |:---------------------------:|:------------:| | system/openlara/*.xsh | Shader files | | saves/openlara/savegame.dat | Savegame | | saves/openlara/settings | Settings | ## Geometry and timing - The OpenLara core's core provided FPS is dependent on the ['Framerate' core option](#core-options). - The OpenLara core's core provided sample rate is 44100 Hz - The OpenLara core's base width is 320 - The OpenLara core's base height is 240 - The OpenLara core's max width is dependent on the ['Internal resolution' core option](#core-options) - The OpenLara core's max height is dependent on the ['Internal resolution' core option](#core-options) - The OpenLara core's core provided aspect ratio is 4/3 ## Core options The OpenLara core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Framerate (restart)** [openlara_framerate] (**60fps**|70fps|72fps|75fps|90fps|100fps|119fps|120fps| 144fps|240fps|244fps|15fps|30fps) Modify framerate. Requires a restart. - **Internal resolution (restart)** [openlara_resolution] (**320x240**|360x480|480x272|512x384|512x512|640x240| 640x448|640x480|720x576|800x600|960x720|1024x768| 1024x1024|1280x720|1280x960|1600x1200|1920x1080| 1920x1440|1920x1600|2048x2048|2560x1440| 3840x2160|7680x4320|15360x8640|16000x9000) Modify the internal resolution. Requires a restart. ??? note "Internal resolution - 320x240" ![](../image/core/openlara/320x240_2.png) ??? note "Internal resolution - 1920x1080" ![](../image/core/openlara/1920x1080_2.png) ## Joypad | RetroPad Inputs | User 1 input descriptors | |------------------------------------------------|--------------------------| | ![](../image/retropad/retro_b.png) | Action (Shoot/grab) | | ![](../image/retropad/retro_y.png) | Jump | | ![](../image/retropad/retro_select.png) | Inventory | | ![](../image/retropad/retro_start.png) | Start | | ![](../image/retropad/retro_dpad_up.png) | Up | | ![](../image/retropad/retro_dpad_down.png) | Down | | ![](../image/retropad/retro_dpad_left.png) | Left | | ![](../image/retropad/retro_dpad_right.png) | Right | | ![](../image/retropad/retro_a.png) | Roll | | ![](../image/retropad/retro_x.png) | Draw weapon | | ![](../image/retropad/retro_r1.png) | Walk (when holding) | | ![](../image/retropad/retro_l2.png) | Duck/Crouch (TR3 and up) | | ![](../image/retropad/retro_r2.png) | Dash (TR3 and up) | ## External Links - [Official OpenLara Github Repository](https://github.com/XProger/OpenLara) - [Official OpenLara Website](http://xproger.info/projects/OpenLara/) - [Libretro OpenLara Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/openlara_libretro.info) - [Libretro OpenLara Github Repository](https://github.com/libretro/OpenLara) - [Report Libretro OpenLara Core Issues Here](https://github.com/libretro/libretro-meta/issues) ================================================ FILE: docs/library/opera.md ================================================ # The 3DO Company - 3DO (Opera) ## Background Opera is an open-source, low-level emulator for the 3DO Game Console. Opera is a fork of 4DO, originally a port of 4DO, itself a fork of FreeDO, to libretro. The fork/rename occurred due to the original 4DO project being dormant and to differentiate the project due to new development and focus. The Opera core has been authored by - trapexit - JohnnyDude - FreeDO team The Opera core is licensed under - [Modified GNU LGPL / Non-commercial](https://github.com/libretro/opera-libretro/blob/master/libopera/opera_3do.c) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS One of the following system BIOSes is required to run software. Place in the frontend's system directory. | Filename | Description | md5sum | |:---------------------------:|:-----------------------------------:|:--------------------------------:| | panafz1.bin | Panasonic FZ-1 | f47264dd47fe30f73ab3c010015c155b | | panafz10.bin | Panasonic FZ-10 | 51f2f43ae2f3508a14d9f56597e2d3ce | | panafz10-norsa.bin | Panasonic FZ-10 [RSA Patch] | 1477bda80dc33731a65468c1f5bcbee9 | | panafz10e-anvil.bin | Panasonic FZ-10-E [Anvil] | a48e6746bd7edec0f40cff078f0bb19f | | panafz10e-anvil-norsa.bin | Panasonic FZ-10-E [Anvil RSA Patch] | cf11bbb5a16d7af9875cca9de9a15e09 | | panafz1j.bin | Panasonic FZ-1J | a496cfdded3da562759be3561317b605 | | panafz1j-norsa.bin | Panasonic FZ-1J [RSA Patch] | f6c71de7470d16abe4f71b1444883dc8 | | goldstar.bin | Goldstar GDO-101M | 8639fd5e549bd6238cfee79e3e749114 | | sanyotry.bin | Sanyo IMP-21J TRY | 35fa1a1ebaaeea286dc5cd15487c13ea | | 3do_arcade_saot.bin | Shootout At Old Tucson | 8970fc987ab89a7f64da9f8a8c4333ff | ## FONT ROM Required for some Japanese games. Optional otherwise. | Filename | Description | md5sum | |:--------------------------:|:---------------------------:|:--------------------------------:| | panafz1-kanji.bin | Panasonic FZ-1 Kanji ROM | b8dc97f778a6245c58e064b0312e8281 | | panafz10ja-anvil-kanji.bin | Panasonic FZ-10JA Kanji ROM | 428577250f43edc902ea239c50d2240d | | panafz1j-kanji.bin | Panasonic FZ-1J Kanji ROM | c23fb5d5e6bb1c240d02cf968972be37 | ## Extensions Content that can be loaded by the Opera core have the following file extensions: - .iso - .bin - .chd - .cue RetroArch database(s) that are associated with the Opera core: - [The 3DO Company - 3DO](https://github.com/libretro/libretro-database/blob/master/rdb/The%203DO%20Company%20-%203DO.rdb) ## Features Frontend-level settings or features that the Opera core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The Opera core's library name is 'Opera' The Opera core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-------------:|:--------------------------:| | *.srm | Per game NVRAM | | 3DO.nvram | Shared NVRAM | | 3DO.nvram.tmp | Only used for atomic saves | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ### Geometry and timing - The Opera core's core provided FPS is 60 - The Opera core's core provided sample rate is 44100 Hz - The Opera core's base width is 320 when the 'High Resolution' core option is set to disabled. - The Opera core's base height is 240 when the 'High Resolution' core option is set to disabled. - The Opera core's max width is 320 when the 'High Resolution' core option is set to disabled. - The Opera core's max height is 240 when the 'High Resolution' core option is set to disabled. - The Opera core's base width is 640 when the 'High Resolution' core option is set to enabled. - The Opera core's base height is 480 when the 'High Resolution' core option is set to enabled. - The Opera core's max width is 640 when the 'High Resolution' core option is set to enabled. - The Opera core's max height is 480 when the 'High Resolution' core option is set to enabled. - The Opera core's core provided aspect ratio is 4/3 ## Core options The Opera core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **CPU overclock** [opera_cpu_overclock] (**1.0x (12.50Mhz)**|1.1x (13.75Mhz)|1.2x (15.00Mhz)|1.5x (18.75Mhz)|1.6x (20.00Mhz)|1.8x (22.50Mhz)|2.0x (25.00Mhz)) The 3DO used a 12.5MHz ARM60 CPU as its central processor. We have implemented a CPU overclocking feature in the Opera core so that you can increase performance upto 2x. **May not have an impact on all games.** [https://www.youtube.com/watch?v=7bT2ecwKdHQ](https://www.youtube.com/watch?v=7bT2ecwKdHQ) - **High Resolution** [opera_high_resolution] (**disabled**|enabled) The default internal resolution is 320x240, but the output resolution is 640x480. This feature makes the system behave as if it has a 640x480 framebuffer. ??? note "High Resolution - disabled" ![](../image/core/opera/high_off.png) ??? note "High Resolution - enabled" ![](../image/core/opera/high_on.png) - **NVRAM Storage** [opera_nvram_storage] (**per game**|shared) Choose whether NVRAM saves are per game or NVRAM saves are shared between all games. Look at the [Directories section](#directories) for more information. - **Active Devices** [opera_active_devices] (**1**|2|3|4|5|6|7|8|0) There is a bug (maybe in Opera but possibly in certain games) in which having more than 1 controller emulated causes the game not to respond to input. This allows working around the issue. - **Timing Hack 1 (Crash 'n Burn)** [opera_hack_timing_1] (**disabled**|enabled) Enable this to fix Crash 'n Burn. - **Timing Hack 3 (Dinopark Tycoon)** [opera_hack_timing_3] (**disabled**|enabled) Enable this to fix Dinopark Tycoon. - **Timing Hack 5 (Microcosm)** [opera_hack_timing_5] (**disabled**|enabled) Enable this to fix Microcosm. - **Timing Hack 6 (Alone in the Dark)** [opera_hack_timing_6] (**disabled**|enabled) Enable this to fix Alone in the Dark. - **Graphics Step Y Hack (Samurai Shodown)** [opera_hack_graphics_step_y] (**disabled**|enabled) Enable this to fix Samurai Shodown's background rendering. ## Joypad ![](../image/controller/3do.png) | User 1 - 2 Remap descriptors | RetroPad Inputs | |------------------------------|------------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | A | ![](../image/retropad/retro_y.png) | | X (Stop) | ![](../image/retropad/retro_select.png) | | P (Play/Pause) | ![](../image/retropad/retro_start.png) | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | | C | ![](../image/retropad/retro_a.png) | | L | ![](../image/retropad/retro_l1.png) | | R | ![](../image/retropad/retro_r1.png) | ## Compatibility - [Opera Core Compatibility List](http://wiki.fourdo.com/Compatibility_List) ## External Links - [Official 4DO Website](http://www.fourdo.com/) - [Official 4DO Wiki](http://wiki.fourdo.com/Main_Page) - [Official 4DO SourceForge Repository](https://sourceforge.net/projects/fourdo/) - [Libretro Opera Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/opera_libretro.info) - [Libretro Opera Github Repository](https://github.com/libretro/opera-libretro) - [Report Libretro Opera Core Issues Here](https://github.com/libretro/opera-libretro/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0IeD-Mj2GG13qsYasGgRNQg4) ================================================ FILE: docs/library/pcsx2.md ================================================ # Sony - PlayStation (LRPS2) Click on this link here to get redirected to the LRPS2 page. ================================================ FILE: docs/library/pcsx_rearmed.md ================================================ # Sony - PlayStation (PCSX ReARMed) ## Background PCSX ReARMed is a fork of PCSX Reloaded. It differs from the latter in that it has special optimizations for systems that have an ARM architecture-based CPU. The PCSX ReARMed core has been authored by - PCSX Team - notaz - Exophase The PCSX ReARMed core is licensed under - [GPLv2](https://github.com/libretro/pcsx_rearmed/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Required or optional firmware files go in the frontend's `system` directory. If more than one BIOS file exists, the PCSX ReARMed core uses the BIOS above the table below. !!! attention In case the PCSX ReARMed core can find no BIOS files named like this in RetroArch's system directory, it will default to a High-Level Emulation BIOS. This decreases the level of compatibility of the emulator, so it is recommended that you always supply valid BIOS images inside the system directory. | Filename | Description | md5sum | |:---------------:|:----------------------:|:--------------------------------:| | PSXONPSP660.bin | Extracted from a PSP | c53ca5908936d412331790f4426c6c33 | | scph101.bin | Version 4.4 03/24/00 A | 6E3735FF4C7DC899EE98981385F6F3D0 | | scph7001.bin | Version 4.1 12/16/97 A | 1e68c231d0896b7eadcad1d7d8e76129 | | scph5501.bin | Version 3.0 11/18/96 A | 490f666e1afb15b7362b406ed1cea246 | | scph1001.bin | Version 2.0 05/07/95 A | 924e392ed05558ffdb115408c263dccf | If none of the above is found, PCSX_ReARMed will search for filenames starting with "scph" and use that instead. It doesn't seem to matter whatever BIOS version is used and from what region, as long as it's from a retail PSX/PS one. If no compatible BIOS is found, PCSX_ReARMed will revert to use the HLE BIOS, which can have compatibility issues (e.g. memory card issues in Suikoden games, some games just going into black screens, ...). ## Extensions Content that can be loaded by the PCSX ReARMed core have the following file extensions: - .bin - .cue - .img - .mdf - .pbp - .toc - .cbn - .m3u - .ccd - .chd - .iso - .exe RetroArch database(s) that are associated with the PCSX ReARMed core: - [Sony - PlayStation](https://github.com/libretro/libretro-database/blob/master/rdb/Sony%20-%20PlayStation.rdb) ## Features Frontend-level settings or features that the PCSX ReARMed core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✔ | | Rumble | ✔ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✔ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The PCSX ReARMed core's library name is 'PCSX-ReARMed' The PCSX ReARMed core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:--------------:|:----------------------------------------------------:| | *.srm | Memory card slot 0 | | pcsx-card2.mcd | Memory card slot 1 (if enabled, default to disabled) | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ### Geometry and timing - The PCSX ReARMed core's core provided FPS is 60 for NTSC games. 50 for PAL games. - The PCSX ReARMed core's core provided sample rate is 44100 Hz - The PCSX ReARMed core's base width is 320 - The PCSX ReARMed core's base height is 240 - The PCSX ReARMed core's max width is 1024 - The PCSX ReARMed core's max height is 512 - The PCSX ReARMed core's core provided aspect ratio is 4/3 ### Loading content PCSX ReARMed needs a cue-sheet that points to an image file. A cue sheet, or cue file, is a metadata file which describes how the tracks of a CD or DVD are laid out. If you have e.g. `foo.bin`, you should create a text file and save it as `foo.cue`. Most PS1 games are single-track, so the cue file contents should look like this: `foobin.cue` ``` FILE "foo.bin" BINARY TRACK 01 MODE1/2352 INDEX 01 00:00:00 ``` After that, you can load the `foo.cue` file in RetroArch with the PCSX ReARMed core. !!! attention Certain PS1 games are multi-track, so their .cue files might be more complicated. #### Playing PAL copy protected games PAL copy protected games need a SBI Subchannel file next to the bin/cue files in order to get past the copy protection. - Ape Escape (Europe).bin - Ape Escape (Europe).cue - **Ape Escape (Europe).sbi** #### Multiple-disk games If foo is a multiple-disk game, you should have .cue files for each one, e.g. `foo (Disc 1).cue`, `foo (Disc 2).cue`, `foo (Disc 3).cue`. To take advantage of PCSX ReARMed's Disk Control feature for disk swapping, an index file (a m3u file) should be made. Create a text file and save it as `foo.m3u`. Then enter your game's .cue files on it. The m3u file contents should look something like this: `foo.m3u` ``` foo (Disc 1).cue foo (Disc 2).cue foo (Disc 3).cue ``` After that, you can load the `foo.m3u` file in RetroArch with the PCSX ReARMed core. Here's a m3u example done with Valkryie Profile `Valkyrie Profile (USA).m3u` ``` Valkyrie Profile (USA) (Disc 1).cue Valkyrie Profile (USA) (Disc 2).cue ``` ![](../image/core/beetle_psx_hw/m3u.png) !!! attention Adding multi-track games to a RetroArch playlist is recommended. (Manually add an entry a playlist that points to `foo.m3u`) ### Swapping disks Swapping disks follows this procedure 1. Open tray (Disk Cycle Tray Status) 2. Change the Disk Index to the disk you want to swap to. 3. Close tray (Disk Cycle Tray Status) 4. Return to the game and wait a few seconds to let it take effect ### PBP Alternatively to using cue sheets with .bin/.iso files, you can convert your games to .pbp (Playstation Portable update file). A recommended .pbp convert tool is PSX2PSP. If converting a multiple-disk game, all disks should be added to the same .pbp file, rather than making a .m3u file for them. Most conversion tools will want a single .bin file for each disk. If your game uses multiple .bin files (tracks) per disk, you will have to mount the cue sheet to a virtual drive and re-burn the images onto a single track before conversion. !!! attention RetroArch does not currently have .pbp database due to variability in users' conversion methods. All .pbp games will have to be added to playlists manually. ## Saves For game savedata storage, the PSX console used memory cards. The PSX console had two slots for memory cards. The PCSX ReARMed core defaults to only support the first memory card slot. Second memory card slot can be enabled via the `pcsx_rearmed_memcard2` option. In this doc, the first memory card slot will be referred to as 'Memcard slot 0'. The second memory card slot will be referred to as 'Memcard slot 1'. For memory card functionality and usage, the PCSX ReARMed core will the Libretro savedata format.
| Libretro savedata format | |--------------------------| | gamename.srm | | pcsx-card2.mcd |
**By default**, the filename of the Memcard slot 0 savedata will match the loaded cue or m3u or pbp filename, like this: **By default**, the filename of the Memcard slot 1 savedata (if enabled) will be `pcsx-card2.mcd`. This basically means that all games in the same folder share the same nemory card in slot 1. - Loaded content: Breath of Fire III (USA).cue - **Memcard slot 0: Breath of Fire III (USA).srm** or - Loaded content: Final Fantasy VII (USA).m3u - **Memcard slot 0: Final Fantasy VII (USA).srm** or - Loaded content: Wild Arms 2 (USA).pbp - **Memcard slot 0: `Wild Arms 2 (USA).srm** !!! attention To import your old memory cards from other emulators, you need to rename them to the Libretro savedata format. !!! warning Keep in mind that save states also include the state of the memory card; carelessly loading an old save state will **OVEWRITE** the memory card, potentially resulting in lost saved games. **You can set the 'Don't overwrite SaveRAM on loading savestate' option in RetroArch's Saving settings to On to prevent this.** ## Core options The PCSX ReARMed core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Frameskip** [pcsx_rearmed_frameskip] (**0**|1|2|3) Choose how much frames should be skipped to improve performance at the expense of visual smoothness. - **Use BIOS** [pcsx_rearmed_bios] (**auto**|HLE) Allows you to use real bios file (if available) or emulated bios (HLE). **HLE** - Forces core to use built-in bios emulation **auto** - Tries to search for compatible bios file, falls back to use HLE if none is found. - **Region** [pcsx_rearmed_region] (**auto**|NTSC|PAL) Choose what region the system is from. - **Enable second memory card** [pcsx_rearmed_memcard2] (**disabled**|enabled) Enables or disabled second memory card (Memcard 2 slot). When enabled, Memcard 2 slot's save data will be loaded and saved as `pcsx-card2.mcd` file in the saves directory. All games will share the same second memory card. - **Emulated Mouse Sensitivity** [pcsx_rearmed_input_sensitivity] (**1.00**|0.05 - 2.00) Adjust movement responsiveness for the emulated mouse device. - **Multitap Mode (Restart)** [pcsx_rearmed_multitap] (**disabled**|port 1 only|port 2 only|both) Sets the multitap device in either port 1 or port 2 allowing support of upto 5 players, or on both for 8 players. !!! attention Multitap option works depending on the game. Setting any mode on a game that does not use multitap will make inputs not working. Leave mode at **disabled** unless supported by game and you really to play in multiplayer modes. - **NegCon Twist Deadzone (percent)** [pcsx_rearmed_negcon_deadzone] (**0**|5|10|15|20|25|30) Sets the deadzone of the RetroPad left analog stick when simulating the 'twist' action of emulated [neGcon Controllers](https://en.wikipedia.org/wiki/NeGcon). Used to eliminate drift/unwanted input. !!! attention Most (all?) negCon compatible titles provide in-game options for setting a 'twist' deadzone value. To avoid loss of precision, the in-game deadzone should *always* be set to zero. Any analog stick drift should instead be accounted for by configuring the 'NegCon Twist Deadzone' core option. This is particularly important when 'NegCon Twist Response' is set to 'quadratic' or 'cubic'. Xbox gamepads typically require a deadzone of 15-20%. Many Android-compatible bluetooth gamepads have an internal 'hardware' deadzone, allowing the deadzone value here to be set to 0%. For convenience, it is recommended to make use of the 'Options → Analog Setting 1P' menu of [Gran Turismo](https://en.wikipedia.org/wiki/Gran_Turismo_(video_game)) when calibrating the 'NegCon Twist Deadzone'. This provides a clear and precise representation of 'real' controller input values. - **NegCon Twist Response** [pcsx_rearmed_negcon_response] (**linear**|quadratic|cubic) Specifies the analog response when using a RetroPad left analog stick to simulate the 'twist' action of emulated [neGcon Controllers](https://en.wikipedia.org/wiki/NeGcon). 'linear': Analog stick displacement is mapped linearly to negCon rotation angle. Recommended when using racing wheel peripherals. 'quadratic': Analog stick displacement is mapped quadratically to negCon rotation angle. This allows for greater precision when making small movements with the analog stick. Optimal setting for gamepads. 'cubic': Analog stick displacement is mapped cubically to negCon rotation angle. This allows for even greater precision when making small movements with the analog stick, but 'exaggerates' larger movements. Enables precise control but difficult to use. !!! attention A linear response is not recommended when using standard gamepad devices. The negCon 'twist' mechanism is substantially different from conventional analog sticks; linear mapping over-amplifies small displacements of the stick, impairing fine control. A linear response is only appropriate when using racing wheel peripherals. In most cases, the 'quadratic' option should be selected. This provides effective compensation for the physical differences between real/emulated hardware, enabling smooth/precise analog input. - **Analog axis bounds** [pcsx_rearmed_analog_axis_modifier] (**circle**|square) Range bounds for analog axis. Square bounds help controllers with highly circular ranges that are unable to fully saturate the x and y axis at 45degree deflections. - **Guncon Adjust X** [pcsx_rearmed_gunconadjustx] (**0**|-25 - 25) - **Guncon Adjust Y** [pcsx_rearmed_gunconadjustx] (**0**|-25 - 25) When using Guncon mode, you can override aim in emulator if shots misaligned, this applies an increment on the x or y axis. - **Guncon Adjust Ratio X** [pcsx_rearmed_gunconadjustratiox] (**1**|0.75 - 1.25) - **Guncon Adjust Ratio Y** [pcsx_rearmed_gunconadjustratioy] (**1**|0.75 - 1.25) When using Guncon mode, you can override aim in emulator if shots misaligned, this applies a ratio on the x or y axis. - **Enable Vibration** [pcsx_rearmed_vibration] (**enabled**|disabled) Enables Rumble. Look at the [Rumble section](#rumble-support) for more information. - **Enable Dithering** [pcsx_rearmed_dithering] (**enabled**|disabled) If Off, disables the dithering pattern the PSX applies to combat color banding. ??? note "Enable Dithering - On" ![](../image/core/pcsx_rearmed/dither_on.png) ??? note "Enable Dithering - Off" ![](../image/core/pcsx_rearmed/dither_off.png) - **Frame duping** [pcsx_rearmed_duping_enable] (**enabled**|disabled) A speedup, redraws/reuses the last frame if there was no new data. - **Display Internal FPS** [pcsx_rearmed_display_internal_fps] (**disabled**|enabled) Shows an on-screen frames per second counter. - **Threaded Rendering** [pcsx_rearmed_gpu_thread_rendering] (**disabled**|sync|async) When enabled, runs GPU commands in a thread. 'Sync' waits for drawing to finish before vsync. 'Async' will not wait unless there's another frame behind it. - **Show Bios Bootlogo(Breaks some games)** [pcsx_rearmed_show_bios_bootlogo] (**disabled**|enabled) Show the BIOS bootlogo. ??? note "Skip BIOS - Off" ![](../image/core/beetle_psx_hw/bios.png) - **Sound: Reverb** [pcsx_rearmed_spu_reverb] (**enabled**|disabled) Enable sound reverb. - **Sound: Interpolation** [pcsx_rearmed_spu_interpolation] (**simple**|gaussian|cubic|off) Modify sound interpolation. - **CD Access Method (Restart)** [pcsx_rearmed_async_cd] (**sync**|sync|async|precache) Select method used to read data from content disk images. 'Synchronous': Mimics original hardware. 'Asynchronous': Reduce stuttering on devices with slow storage. 'Precache': Loads disk image into memory for faster access (**Note: CHD only**). - **Advanced System Options** - **XA Decoding** [pcsx_rearmed_noxadecoding] (**enabled**|disabled) Disables XA sound, which can sometimes improve performance. - **CD Audio** [pcsx_rearmed_nocdaudio] (**enabled**|disabled) Disables XA sound, which can sometimes improve performance. - **SPU IRQ Always Enabled** [pcsx_rearmed_spuirq] (**disabled**|enabled) Compatibility tweak, should be left to off in most cases. This can be momentarily turned on at any point to try and fix some bugs. Few examples includes: 'Alien Resurrection': bug where doors can remain closed until the option is turned on. 'Legend of Mana': audio out-of-sync bug during FMV sequences can also be fixed by momentarily switching the option on, then off when sound is normal. - **Additional game fixes options** - **Diablo Music Fix** [pcsx_rearmed_idiablofix] (**disabled**|enabled) Fix for music randomly cuts out when pressing start or interact with somebody. - **Parasite Eve 2/Vandal Hearts 1/2 Fix** [pcsx_rearmed_pe2_fix] (**disabled**|enabled) Enable this to fit Parasite Eve 2 and Vandal Hearts 1/2 - **InuYasha Sengoku Battle Fix** [pcsx_rearmed_inuyasha_fix] (**disabled**|enabled) Enable this to fix InuYasha. - **Additional core options for DynaRec (ari64) builds:** - **Dynamic recompiler** [pcsx_rearmed_drc] (**enabled**|disabled) Enables core to use dynamic recompiler or interpreter (slower) cpu instructions. When enabled, dynarec can use either one below: Dynarec can either be **ari64** for arm 32-bit devices while **lightrec** i used for 64-bit capable devices or platforms. - **PSX cpu clock** [pcsx_rearmed_psxclock] (30 - 100, **default 57**) Overclock or underclock the PSX, default is 57. Lower value = less work for the emu, may be faster in some cases. Causes compatibility issues, so modify only for games that needs it, leave at default for most games. - **Additional core options for devices using NEON-compatible CPU:** - **Enable interlacing mode(s)** [pcsx_rearmed_neon_interlace_enable] (**disabled**|enabled) Enables fake scanlines effect. - **Enhanced resolution (slow)** [pcsx_rearmed_neon_enhancement_enable] (**disabled**|enabled) Renders in double resolution at the cost of lower performance Not available for high resolution games. - **Enhanced resolution speed hack** [pcsx_rearmed_neon_enhancement_no_main] (**disabled**|enabled) Speed hack for above option. Causes game glitches. - **Additional core options for devices using PEOPS GPU plugin** (some options may or may not have effect or need core restart) - **(GPU) Odd/Even Bit Hack** [pcsx_rearmed_gpu_peops_odd_even_bit] (**disabled**|enabled) Needed for Chrono Chross. - **(GPU) Expand Screen Width** [pcsx_rearmed_gpu_peops_expand_screen_width] (**disabled**|enabled) Capcom fighting games. - **(GPU) Ignore Brightness Color** [pcsx_rearmed_gpu_peops_ignore_brightness] (**disabled**|enabled) Black screens in Lunar. - **(GPU) Disable Coordinate Check** [pcsx_rearmed_gpu_peops_disable_coord_check] (**disabled**|enabled) Enables compatibility mode. - **(GPU) Lazy Screen Update** [pcsx_rearmed_gpu_peops_lazy_screen_update] (**disabled**|enabled) Pandemonium 2 - **(GPU) Old Frame Skipping** [pcsx_rearmed_gpu_peops_old_frame_skip] (**enabled**|disabled) Skips every second frame. - **(GPU) Repeated Flat Tex Triangles** [pcsx_rearmed_gpu_peops_repeated_triangles] (**disabled**|enabled) Needed by Dark Forces. - **(GPU) Draw Quads with Triangles** [pcsx_rearmed_gpu_peops_quads_with_triangles] (**disabled**|enabled) Better G-colors, worse textures. - **(GPU) Fake 'Gpu Busy' States** [pcsx_rearmed_gpu_peops_fake_busy_state] (**disabled**|enabled) Toggle busy flag after drawing. - **Additional core options for devices using UNAI GPU plugin** (some options may or may not have effect or need core restart) - **(GPU) Enable Blending** [pcsx_rearmed_gpu_unai_blending] (**enabled**|disabled) - **(GPU) Enable Lighting** [pcsx_rearmed_gpu_unai_lighting] (**enabled**|enabled) - **(GPU) Enable Fast Lighting** [pcsx_rearmed_gpu_unai_fast_lighting] (**disabled**|enabled) - **(GPU) Enable Forced Interlace** [pcsx_rearmed_gpu_unai_ilace_force] (**disabled**|enabled) - **(GPU) Enable Pixel Skip** [pcsx_rearmed_gpu_unai_pixel_skip] (**disabled**|enabled) - **(GPU) Enable Hi-Res Downscaling** [pcsx_rearmed_gpu_unai_scale_hires] (**disabled**|enabled) When enabled, will scale hi-res modes to 320x240, skipping unrendered pixels. ## Rumble Rumble only works in the PCSX ReARMed core when - The content being ran has rumble support. - The frontend being used has rumble support. - The joypad device being used has rumble support. - The ['Enable Vibration' core option](#core-options) is set to On - The corresponding user's Pad Type is set to **analog** ## Multitap Activating multitap support in compatible games can be configured by the ['Multitap 1' and 'Multitap 2' core options](#core-options). - When multitap1 and multitap2 are off, only User 1 and 2 input works and are assigned as player 1 and player 2 respectively. ## Joypad ![](../image/controller/psx.png) | RetroPad Inputs | User 1 - 8 input descriptors | standard | analog | negcon | |------------------------------------------------|------------------------------|-------------|----------------|---------------------------------| | ![](../image/retropad/retro_b.png) | Cross | Cross | Cross | Analog Button I | | ![](../image/retropad/retro_y.png) | Square | Square | Square | Analog Button II | | ![](../image/retropad/retro_select.png) | Select | Select | Select | | | ![](../image/retropad/retro_start.png) | Start | Start | Start | Start | | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | D-Pad Up | D-Pad Up | D-Pad Up | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | D-Pad Down | D-Pad Down | D-Pad Down | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | D-Pad Left | D-Pad Left | D-Pad Left | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | D-Pad Right | D-Pad Right | D-Pad Right | | ![](../image/retropad/retro_a.png) | Circle | Circle | Circle | A | | ![](../image/retropad/retro_x.png) | Triangle | Triangle | Triangle | B | | ![](../image/retropad/retro_l1.png) | L1 | L1 | L1 | Left Shoulder Button (analog) | | ![](../image/retropad/retro_r1.png) | R1 | R1 | R1 | Right Shoulder Button (digital) | | ![](../image/retropad/retro_l2.png) | L2 | L2 | L2 | Analog Button II | | ![](../image/retropad/retro_r2.png) | R2 | R2 | R2 | Analog Button I | | ![](../image/retropad/retro_l3.png) | L3 | | L3 | | | ![](../image/retropad/retro_r3.png) | R3 | | R3 | | | ![](../image/retropad/retro_left_stick.png) X | Left Analog X | | Left Analog X | Twist | | ![](../image/retropad/retro_left_stick.png) Y | Left Analog Y | | Left Analog Y | | | ![](../image/retropad/retro_right_stick.png) X | Right Analog X | | Right Analog X | | | ![](../image/retropad/retro_right_stick.png) Y | Right Analog Y | | Right Analog Y | Up: Analog Button I / Down: Analog Button II | ## Compatibility | Game | Issue | |-----------------|--------------------------------------------------------| | Jumping Flash 2 | Graphics glitches. Geometry issues. | | Tobal 2 | Graphics glitch. Garbled Dream Factory intro sequence. | | Kitty the Kool! | No issues. | ## External Links - [Official PCSX ReARMed Website](http://notaz.gp2x.de/pcsx_rearmed.php) - [Official PCSX ReARMed Github Repository](https://github.com/notaz/pcsx_rearmed) - [Libretro PCSX ReARMed Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/pcsx_rearmed_libretro.info) - [Libretro PCSX ReARMed Github Repository](https://github.com/libretro/pcsx_rearmed) - [Report Libretro PCSX ReARMed Core Issues Here](https://github.com/libretro/pcsx_rearmed/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0Ie5y2yx-sl5xn6KRbo5VUMf) ## PSX - [Sony - PlayStation (Beetle PSX)](beetle_psx.md) - [Sony - PlayStation (Beetle PSX HW)](beetle_psx_hw.md) ================================================ FILE: docs/library/pd777.md ================================================ # Epoch - Cassette Vision (PD777) ## Background μPD777 is an emulator for the Epoch Cassette Vision, from Japan in 1981. It was one of the first Japanese consoles with interchangeable cartridges, but included a full CPU in each cartridge --- the console base was mostly buttons and wires. The Cassette Vision Jr (1983) used the same software, but dropped the paddle controls. PD777 is a Libretro port, to run in RetroArch. The PD777 core has been authored by: - W88DodPECuThLOl (Standalone PD777) - Ken Mitton The PD777 core is licensed under: - [MIT](https://github.com/mittonk/PD777/blob/main/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Requirements Minimal. ## How to start the PD777 core: ROM file handling is slightly awkward because of the two-file ROM format. 1. Zip-files (bundling one `.bin777` and one `.ptn777`) are supported. 1. Supply a `.bin777` file to load; the core looks for a similarly-named `.ptn777` file in the same directory. There is not yet a suitable single-file format for the Cassette Vision. If ROM loading fails, the core will run a built-in balloon demo, as in standalone emulator. ## BIOS None. ## Extensions Content that can be loaded by the PD777 core have the following file extensions: - .zip - .bin777 RetroArch database(s) that are associated with the PD777 core: - None yet ## Features Frontend-level settings or features that the PD777 core respects: | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✕ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Directories None. ## Geometry and timing - The PD777 core's core provided FPS is 60. - The PD777 core's core provided sample rate is 48000/00 Hz. - The PD777 core's base width is 375. - The PD777 core's base height is 240. - The PD777 core's core provided aspect ratio is 4:3. 375x240, 60 FPS. ## Usage Standard. ## Core options Input > Announce Course Switch: Show the new setting of the Course Select Switch when changing it with up/down buttons. ## User 1 device types The PD777 core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): - **RetroPad** - RetroPad w/Analog - Mouse ## Joypad The controls were built into the base unit, and some 2-player games assign buttons asymmetrically; for example, New Baseball gives most of the buttons to the fielding player, with just Lever Switch 1 for the batting player. | RetroPad Inputs | User # input descriptors | (Device name) Inputs | |------------------------------------------------|--------------------------|---------------------------| | ![](../image/retropad/retro_b.png) | Push2 | - | | ![](../image/retropad/retro_y.png) | Push3 | - | | ![](../image/retropad/retro_select.png) | Select | - | | ![](../image/retropad/retro_start.png) | Start | - | | ![](../image/retropad/retro_dpad_up.png) | Course Select increment | - | | ![](../image/retropad/retro_dpad_down.png) | Course Select decrement | - | | ![](../image/retropad/retro_dpad_left.png) | Lever Switch 1 Left | - | | ![](../image/retropad/retro_dpad_right.png) | Lever Switch 1 Right | - | | ![](../image/retropad/retro_a.png) | Push4 | - | | ![](../image/retropad/retro_x.png) | Push1 | - | | ![](../image/retropad/retro_l1.png) | | - | | ![](../image/retropad/retro_r1.png) | AUX | - | | ![](../image/retropad/retro_l2.png) | | - | | ![](../image/retropad/retro_r2.png) | | - | | ![](../image/retropad/retro_l3.png) | | - | | ![](../image/retropad/retro_r3.png) | | - | | ![](../image/retropad/retro_left_stick.png) X | Paddle 2 | - | | ![](../image/retropad/retro_left_stick.png) Y | Paddle 1 | - | | ![](../image/retropad/retro_right_stick.png) X | | - | | ![](../image/retropad/retro_right_stick.png) Y | | - | RetroPad 2 gets Lever Switch 2 and Paddles 3 and 4. ## External Links - [Standalone PD777 Repository](https://github.com/W88DodPECuThLOl/PD777) - [Libretro PD777 Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/pd777_libretro.info) - [Libretro PD777 Github Repository](https://github.com/mittonk/PD777) - [Report Libretro PD777 Core Issues Here](https://github.com/mittonk/PD777/issues) ## (Related cores) None. ================================================ FILE: docs/library/picodrive.md ================================================ # Sega - MS/MD/CD/32X (PicoDrive) ## Background PicoDrive is an open-source Sega 8/16 bit and 32X emulator which was written having ARM-based handheld devices in mind. ## Features - Supports 32x emulation. - Designed to run on weak devices. The PicoDrive core has been authored by - notaz - fdave The PicoDrive core is licensed under - [Non-commercial](https://github.com/libretro/picodrive/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:-------------:|:-------------------------:|:--------------------------------:| | bios_CD_E.bin | MegaCD EU BIOS - Required | e66fa1dc5820d254611fdcdba0662372 | | bios_CD_U.bin | SegaCD US BIOS - Required | 2efd74e3232ff260e371b99f84024f7f | | bios_CD_J.bin | MegaCD JP BIOS - Required | 278a9397d192149e84e820ac621a8edd | ## Extensions Content that can be loaded by the PicoDrive core have the following file extensions: - .bin - .gen - .smd - .md - .32x - .cue - .iso - .sms - .68k - .chd RetroArch database(s) that are associated with the PicoDrive core: - [Sega - Master System - Mark III](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20Master%20System%20-%20Mark%20III.rdb) - [Sega - Mega-CD - Sega CD](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20Mega-CD%20-%20Sega%20CD.rdb) - [Sega - Mega Drive - Genesis](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20Mega%20Drive%20-%20Genesis.rdb) - [Sega - PICO](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%20PICO.rdb) - [Sega - 32X](https://github.com/libretro/libretro-database/blob/master/rdb/Sega%20-%2032X.rdb) ## Features Frontend-level settings or features that the PicoDrive core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✔ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✔ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Directories The PicoDrive core's library name is 'PicoDrive' The PicoDrive core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:---------------------:| | *.srm | Cartridge backup save | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ## Geometry and timing - The PicoDrive core's core provided FPS is 60 for NTSC games and 50 for PAL games. - The PicoDrive core's core provided sample rate is 44100 Hz - The PicoDrive core's base width is 320 - The PicoDrive core's base height is 224 - The PicoDrive core's max width is 320 - The PicoDrive core's max height is 240 - The PicoDrive core's core provided aspect ratio is 10/7 when the ['Core-provided aspect ratio' core option](#core-options) is set to PAR - The PicoDrive core's core provided aspect ratio is 4/3 when the ['Core-provided aspect ratio' core option](#core-options) is set to 4/3 - The PicoDrive core's core provided aspect ratio is 5/4 when the ['Core-provided aspect ratio' core option](#core-options) is set to CRT ## Loading Sega CD games When loading Sega CD games, PicoDrive needs a cue-sheet that points to an image file. A cue sheet, or cue file, is a metadata file which describes how the tracks of a CD or DVD are laid out. If you have e.g. `foo.bin`, you should create a text file and save it as `foo.cue`. If the Sega CD game is single-track, the cue file contents should look like this: ``` FILE "foo.bin" BINARY TRACK 01 MODE1/2352 INDEX 01 00:00:00 ``` After that, you can load the `foo.cue` file in RetroArch with the PicoDrive core. !!! warning "" Certain Sega CD games are multi-track, so their .cue files might be more complicated. Here's a cue file example done with Lunar - Eternal Blue (USA) ![](../image/core/genesis_plus_gx/cue.png) ## Core options The PicoDrive core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Input device 1** [picodrive_input1] (**3 button pad**/6 button pad/None) Choose which kind of controller is plugged in slot 1. - **"Input device 2** [picodrive_input2] (**3 button pad**/6 button pad/None) Choose which kind of controller is plugged in slot 2. - **No sprite limit** [picodrive_sprlim] (**disabled**/enabled) Enable this to remove the sprite limit. - **MegaCD RAM cart** [picodrive_ramcart] (**disabled**/enabled) Emulate a [MegaCD RAM cart](https://segaretro.org/CD_BackUp_RAM_Cart). - **Region** [picodrive_region] (**Auto**/Japan NTSC/Japan PAL/US/Europe) Force a specific region. - **Core-provided aspect ratio** [picodrive_aspect] (**PAR**/4/3/CRT) Choose the core-provided aspect ratio. RetroArch's aspect ratio must be set to Core provided in the Video settings. ??? note "Core-provided aspect ratio - PAR" ![](../image/core/picodrive/par.png) ??? note "Core-provided aspect ratio - 4/3" ![](../image/core/picodrive/4by3.png) ??? note "Core-provided aspect ratio - CRT" ![](../image/core/picodrive/crt.png) - **Show Overscan** [picodrive_overscan] (**disabled**/enabled) Crop out the potentially random glitchy video output that would have been hidden by the bezel around the edge of a standard-definition television screen. ??? note "Show Overscan - Off" ![](../image/core/picodrive/off.png) ??? note "Show Overscan - On" ![](../image/core/picodrive/on.png) - **68k overclock** [picodrive_overclk68k] (**disabled**/+25%/+50%/+75%/+100%/+200%/+400%) Overclock the emulated [68k chip](http://segaretro.org/M68000) - **Dynamic recompilers** [picodrive_drc] (**enabled**/disabled) Enable dynamic recompilers which help to improve performance. **This core option is not available on all hardware.** - **Audio filter** [picodrive_audio_filter] (**disabled**|low-pass) Enable a low pass audio filter to better simulate the characteristic sound of a Model 1 Genesis. !!! attention This option is ignored when running Master System and PICO titles. Only the Genesis and its add-on hardware (Sega CD, 32X) employed a physical low pass filter. - **Low-pass filter %** [picodrive_lowpass_range] (**60**|65|70|75|80|85|90|95|5|10|15|20|25|30|35|40|45|50|55) Specify the cut-off frequency of the audio low pass filter. A higher value increases the perceived 'strength' of the filter, since a wider range of the high frequency spectrum is attenuated. ## User 1 - 2 device types The PicoDrive core supports the following device type(s). - None - Input is disabled - Can be switched to using the Input device core options. - **3 button pad** - Joypad - Can be switched to using the Input device core options. - 6 button pad - Joypad - Can be switched to using the Input device core options. - SMS pad - Joypad - Is automatically switched to when a Sega Master System game is loaded. ## Joypad | RetroPad Inputs | User 1 - 2 input descriptors | 3 button pad | 6 button pad | |------------------------------------------------|------------------------------|--------------|--------------| | ![](../image/retropad/retro_b.png) | B | B | B | | ![](../image/retropad/retro_y.png) | A | A | A | | ![](../image/retropad/retro_select.png) | Mode | | Mode | | ![](../image/retropad/retro_start.png) | Start | Start | Start | | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | D-Pad Up | D-Pad Up | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | D-Pad Down | D-Pad Down | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | D-Pad Left | D-Pad Left | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | D-Pad Right | D-Pad Right | | ![](../image/retropad/retro_a.png) | C | C | C | | ![](../image/retropad/retro_x.png) | Y | | Y | | ![](../image/retropad/retro_l1.png) | X | | X | | ![](../image/retropad/retro_r1.png) | Z | | Z | | RetroPad Inputs | User 1 - 2 input descriptors | SMS pad | |------------------------------------------------|------------------------------|---------------------------| | ![](../image/retropad/retro_b.png) | Button 1 Start | Button 1 Start | | ![](../image/retropad/retro_start.png) | Button Pause | Button Pause | | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | D-Pad Up | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | D-Pad Down | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | D-Pad Left | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | D-Pad Right | | ![](../image/retropad/retro_a.png) | Button 2 | Button 2 | ## Compatibility | 32x games | Issue | |----------------------------------------------|---------------------------------------------------------------| | Brutal Unleashed – Above the Claw | Softlocks after the first fight. | | FIFA Soccer ’96 | Glitched main menu text. | | Knuckles’ Chaotix | Glitched graphics on the Player Select screen. | | NBA Jam Tournament Edition | Framerate issues. | | NFL Quarterback Club | Some menu graphics are missing. | | Virtua Racing Deluxe | Blinking line during the SEGA logo screen. | | World Series Baseball Starring Deion Sanders | Crashes when starting a match. | | WWF Raw | Various graphics are missing. | ## External Links - [Official PicoDrive Website](http://notaz.gp2x.de/pico.php) - [Official PicoDrive Github Repository](https://github.com/notaz/picodrive) - [Libretro PicoDrive Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/picodrive_libretro.info) - [Libretro PicoDrive Github Repository](https://github.com/libretro/picodrive) - [Report Libretro PicoDrive Core Issues Here](https://github.com/libretro/picodrive/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0IcA87w16rzmzbYJrnxgJJgP) ## Sega 16-bit - [Sega - Master System (Emux SMS)](emux_sms.md) - [Sega - MS/GG/MD/CD (Genesis Plus GX)](genesis_plus_gx.md) - [Sega - MS/GG/SG-1000 (Gearsystem)](gearsystem.md) - [MSX/SVI/ColecoVision/SG-1000 (blueMSX)](bluemsx.md) ================================================ FILE: docs/library/play.md ================================================ # Sony - PlayStation 2 (Play!) ## Background A PS2 emulator for Android, iOS, Windows, MacOS and Linux, written in C++. The Play! core supports OpenGL rendering. The Play! core has been authored by - Zer0xFF - jpd002 The Play! core is licensed under - [MIT](https://github.com/jpd002/Play-/blob/master/License.txt) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Requirements - OpenGL 3.0 or Open GL ES 3.2 or higher for the OpenGL renderer. ## Extensions Content that can be loaded by the Play! core have the following file extensions: - .chd - .cso - .cue - .elf - .iso - .isz RetroArch database(s) that are associated with the Play! core: - [Sony - PlayStation 2](https://github.com/libretro/libretro-database/blob/master/rdb/Sony%20-%20PlayStation%202.rdb) ## Features Frontend-level settings or features that the Play! core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Core options The Play! core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Resolution Multiplier** [play_res_multi] (**1x**|2x|4x|8x) Controls the internal resolution of the graphics, significant performance impact if your GPU is not powerful enough for certain resolutions. - **Presentation Mode** [play_presentation_mode] (**Fit Screen**|Fill Screen|Original Size) Change layout to Fit Screen, Fill Screen or Original Size. - **Force Bilinear Filtering** [play_bilinear_filtering] (enabled|**disabled**) Enable bilinear filtering. ## Joypad ![](../image/controller/psx.png) | User 1 - 8 input descriptors | RetroPad Inputs | PlayStation Controller Inputs | DualShock Inputs | Analog Controller Inputs | Analog Joystick Inputs | neGcon Inputs | |-------------------------------|----------------------------------------------|------------------------------------------------|-------------------------------------------------|-------------------------------------------------|------------------------------------------------|---------------------------------| | Cross | ![](../image/retropad/retro_b.png) | ![](../image/Button_Pack/PS3/PS3_Cross.png) | ![](../image/Button_Pack/PS3/PS3_Cross.png) | ![](../image/Button_Pack/PS3/PS3_Cross.png) | ![](../image/Button_Pack/PS3/PS3_Cross.png) | Analog button I | | Square | ![](../image/retropad/retro_y.png) | ![](../image/Button_Pack/PS3/PS3_Square.png) | ![](../image/Button_Pack/PS3/PS3_Square.png) | ![](../image/Button_Pack/PS3/PS3_Square.png) | ![](../image/Button_Pack/PS3/PS3_Square.png) | Analog button II | | Select | ![](../image/retropad/retro_select.png) | ![](../image/Button_Pack/PS3/PS3_Select.png) | ![](../image/Button_Pack/PS3/PS3_Select.png) | ![](../image/Button_Pack/PS3/PS3_Select.png) | ![](../image/Button_Pack/PS3/PS3_Select.png) | | | Start | ![](../image/retropad/retro_start.png) | ![](../image/Button_Pack/PS3/PS3_Start.png) | ![](../image/Button_Pack/PS3/PS3_Start.png) | ![](../image/Button_Pack/PS3/PS3_Start.png) | ![](../image/Button_Pack/PS3/PS3_Start.png) | Start | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Up.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Up.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Up.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Up.png) | D-Pad Up | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Down.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Down.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Down.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Down.png) | D-Pad Down | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Left.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Left.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Left.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Left.png) | D-Pad Left | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Right.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Right.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Right.png) | ![](../image/Button_Pack/PS3/PS3_Dpad_Right.png) | D-Pad Right | | Circle | ![](../image/retropad/retro_a.png) | ![](../image/Button_Pack/PS3/PS3_Circle.png) | ![](../image/Button_Pack/PS3/PS3_Circle.png) | ![](../image/Button_Pack/PS3/PS3_Circle.png) | ![](../image/Button_Pack/PS3/PS3_Circle.png) | A | | Triangle | ![](../image/retropad/retro_x.png) | ![](../image/Button_Pack/PS3/PS3_Triangle.png) | ![](../image/Button_Pack/PS3/PS3_Triangle.png) | ![](../image/Button_Pack/PS3/PS3_Triangle.png) | ![](../image/Button_Pack/PS3/PS3_Triangle.png) | B | | L1 | ![](../image/retropad/retro_l1.png) | ![](../image/Button_Pack/PS3/PS3_L1.png) | ![](../image/Button_Pack/PS3/PS3_L1.png) | ![](../image/Button_Pack/PS3/PS3_L1.png) | ![](../image/Button_Pack/PS3/PS3_L1.png) | Left shoulder button (analog) | | R1 | ![](../image/retropad/retro_r1.png) | ![](../image/Button_Pack/PS3/PS3_R1.png) | ![](../image/Button_Pack/PS3/PS3_R1.png) | ![](../image/Button_Pack/PS3/PS3_R1.png) | ![](../image/Button_Pack/PS3/PS3_R1.png) | Right shoulder button (digital) | | L2 | ![](../image/retropad/retro_l2.png) | ![](../image/Button_Pack/PS3/PS3_L2.png) | ![](../image/Button_Pack/PS3/PS3_L2.png) | ![](../image/Button_Pack/PS3/PS3_L2.png) | ![](../image/Button_Pack/PS3/PS3_L2.png) | Analog button II | | R2 | ![](../image/retropad/retro_r2.png) | ![](../image/Button_Pack/PS3/PS3_R2.png) | ![](../image/Button_Pack/PS3/PS3_R2.png) | ![](../image/Button_Pack/PS3/PS3_R2.png) | ![](../image/Button_Pack/PS3/PS3_R2.png) | Analog button I | | L3 | ![](../image/retropad/retro_l3.png) | | ![](../image/Button_Pack/PS3/PS3_L3.png) | | | | | R3 | ![](../image/retropad/retro_r3.png) | | ![](../image/Button_Pack/PS3/PS3_R3.png) | | | | | Left Analog X | ![](../image/retropad/retro_left_stick.png) X | | ![](../image/Button_Pack/PS3/PS3_Left_Stick.png) | ![](../image/Button_Pack/PS3/PS3_Left_Stick.png) | Left Joystick X | Twist | | Left Analog Y | ![](../image/retropad/retro_left_stick.png) Y | | ![](../image/Button_Pack/PS3/PS3_Left_Stick.png) | ![](../image/Button_Pack/PS3/PS3_Left_Stick.png) | Left Joystick Y | | | Right Analog X | ![](../image/retropad/retro_right_stick.png) X | | ![](../image/Button_Pack/PS3/PS3_Right_Stick.png) | ![](../image/Button_Pack/PS3/PS3_Right_Stick.png) | Right Joystick X | | | Right Analog Y | ![](../image/retropad/retro_right_stick.png) Y | | ![](../image/Button_Pack/PS3/PS3_Right_Stick.png) | ![](../image/Button_Pack/PS3/PS3_Right_Stick.png) | Right Joystick Y | | ## Compatibility Play! core is still experimental but promising. Some games are already [playable](https://github.com/jpd002/Play-Compatibility/issues?q=is%3Aopen+is%3Aissue+label%3Astate-playable+sort%3Aupdated-desc). ## External Links - [Official Play! Website](https://purei.org) - [Official Play! Github Repository](https://github.com/jpd002/Play-) - [Libretro Play! Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/play_libretro.info) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0If5ArC48Kw2vSC0NmTOdivu) ## Libretro PS2 cores - [PlayStation 2 (LRPS2)](lrps2.md) ================================================ FILE: docs/library/pocketcdg.md ================================================ # PocketCDG ==You have to provide both .cdg and .mp3 file. RetroArch and LibRetro do not share any copyrighted content.== ## Background A MP3 karaoke music player. ### Author/License The PocketCDG core has been authored by - RedBug The PocketCDG core is licensed under - [MIT](https://github.com/libretro/libretro-pocketcdg/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the PocketCDG core have the following file extensions: - .cdg ## Features Frontend-level settings or features that the PocketCDG core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✕ | | Screenshots | ✔ | | Saves | ✕ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The PocketCDG core's internal core name is 'pocketcdg' ### Geometry and timing - The PocketCDG core's core provided FPS is 50 - The PocketCDG core's core provided sample rate is 44100 Hz - The PocketCDG core's core provided aspect ratio is 1 ## Setup Create a folder or put files with both .mp3 and .cdg extensions in the existing folder. The PocketCDG core can load any MP3+CDG file combination. It will then show the lyrics onscreen and on-cue like a true karaoke player, and it will also highlight the text which should be currently sung. ## Controllers The PocketCDG core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 device types - None - Doesn't disable input. There's no reason to switch to this. - **RetroPad** - Joypad - Stay on this. - RetroKeyboard - Keyboard - Has keymapper support but isn't hooked up to any core inputs. There's no reason to switch to this. ### Controller tables #### Joypad | User 1 Remap descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | Pause | ![](../image/retropad/retro_select.png) | | Start | ![](../image/retropad/retro_start.png) | | Up | ![](../image/retropad/retro_dpad_up.png) | | Down | ![](../image/retropad/retro_dpad_down.png) | | Left | ![](../image/retropad/retro_dpad_left.png) | | Right | ![](../image/retropad/retro_dpad_right.png) | | Shutdown | ![](../image/retropad/retro_r1.png) | ## External Links - [Libretro PocketCDG Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/pocketcdg_libretro.info) - [Libretro PocketCDG Github Repository](https://github.com/libretro/libretro-pocketcdg) - [Report Libretro PocketCDG Core Issues Here](https://github.com/libretro/libretro-pocketcdg/issues) ### See also #### Media - [FFmpeg](ffmpeg.md) - [Game Music Emu](game_music_emu.md) - [Imageviewer](imageviewer.md) ================================================ FILE: docs/library/pokemini.md ================================================ # Nintendo - Pokémon Mini (PokeMini) ## Background PokeMini is an emulator for the [Pokémon Mini](https://en.wikipedia.org/wiki/Pok%C3%A9mon_Mini) handheld console. The PokeMini core has been authored by - JustBurn The PokeMini core is licensed under - [GPLv3](https://github.com/libretro/PokeMini/blob/master/LICENSE) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:-------------:|:-----------------------------:|:--------------------------------:| | bios.min | Pokémon Mini BIOS - Optional | 1e4fb124a3a886865acb574f388c803d | ## Extensions Content that can be loaded by the PokeMini core have the following file extensions: - .min RetroArch database(s) that are associated with the PokeMini core: - [Nintendo - Pokemon Mini](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Pokemon%20Mini.rdb) ## Features Frontend-level settings or features that the PokeMini core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✔ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ## Directories The PokeMini core's library name is 'PokeMini' The PokeMini core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-----:|:-----------:| | *.eep | EEPROM save | **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ## Geometry and timing - The PokeMini core's core provided FPS is 72 - The PokeMini core's core provided sample rate is 44100 Hz - The PokeMini core's base width is 96 - The PokeMini core's base height is 64 - The PokeMini core's max width is 576 - The PokeMini core's max height is 384 - The PokeMini core's core provided aspect ratio is 3/2 ## Core options The PokeMini core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Video Scale (Restart)** [pokemini_video_scale] (**4x**|5x|6x|1x|2x|3x) Sets internal video scale factor. Increasing the scale factor improves the appearance of the internal 'dotmatrix' LCD filter. Scale should normally be set to '1x' for correct operation when using an external GPU shader. ??? note "*'dotmatrix' LCD filter - Video Scale - 2x*" ![](../image/core/pokemini/dotmatrix_2x.png) ??? note "*'dotmatrix' LCD filter - Video Scale - 4x*" ![](../image/core/pokemini/dotmatrix_4x.png) ??? note "*'dotmatrix' LCD filter - Video Scale - 6x*" ![](../image/core/pokemini/dotmatrix_6x.png) - **LCD Filter** [pokemini_lcdfilter] (**dotmatrix**|scanline|none) Specifies which internal screen filter should be applied to the display. 'dotmatrix' produces a clean LCD effect, and is the recommended option. LCD filters are disabled when 'Video Scale' is set to '1x'. ??? note "*LCD Filter - dotmatrix*" ![](../image/core/pokemini/dotmatrix.png) ??? note "*LCD Filter - scanline*" ![](../image/core/pokemini/scanline.png) ??? note "*LCD Filter - none*" ![](../image/core/pokemini/none.png) - **LCD Mode** [pokemini_lcdmode] (**analog**|3shades|2shades) Specifies the greyscale 'colour' reproduction characteristics of the emulated liquid crystal display. 'analog' attempts to simulate the Pokémon Mini hardware by allowing smooth time-dependent transitions between 'colour' values. This option is recommended since most games exploited the analog nature of the Pokémon Mini screen to show different shades of 'colour' on a nominally monochrome display. '3shades' reduces the analog greyscale levels to three specific shades and removes all ghosting effects. It is adequate for most games. '2shades' causes the screen to behave as a purely digital monochrome display, either full light or full dark. WARNING: This will cause severe flickering in most games. - **LCD Contrast** [pokemini_lcdcontrast] (**64**|0|16|32|48|80|96) Sets contrast level of emulated liquid crystal display. - **LCD Brightness** [pokemini_lcdbright] (**0**|-80|-60|-40|-20|20|40|60|80) Sets brightness offset of emulated liquid crystal display. - **Palette** [pokemini_palette] (**Default**|Old|Monochrome|Green|Green Vector|Red|Red Vector|Blue LCD|LEDBacklight|Girl Power|Blue|Blue Vector|Sepia|Monochrome Vector) Specifies palette used to 'colourise' the emulated liquid crystal display. 'Default' provides a close approximation of the natural screen tint of the original Pokémon Mini hardware. Palettes with a 'Vector' suffix correspond to inverted colours. ??? note "*Palette - Default*" ![](../image/core/pokemini/Default.png) ??? note "*Palette - Old*" ![](../image/core/pokemini/Old.png) ??? note "*Palette - Monochrome*" ![](../image/core/pokemini/Monochrome.png) ??? note "*Palette - Green*" ![](../image/core/pokemini/Green.png) ??? note "*Palette - Green Vector*" ![](../image/core/pokemini/Green_Vector.png) ??? note "*Palette - Red*" ![](../image/core/pokemini/Red.png) ??? note "*Palette - Red Vector*" ![](../image/core/pokemini/Red_Vector.png) ??? note "*Palette - Blue LCD*" ![](../image/core/pokemini/Blue_LCD.png) ??? note "*Palette - LEDBacklight*" ![](../image/core/pokemini/LEDBacklight.png) ??? note "*Palette - Girl Power*" ![](../image/core/pokemini/Girl_Power.png) ??? note "*Palette - Blue*" ![](../image/core/pokemini/Blue.png) ??? note "*Palette - Blue Vector*" ![](../image/core/pokemini/Blue_Vector.png) ??? note "*Palette - Sepia*" ![](../image/core/pokemini/Sepia.png) ??? note "*Palette - Monochrome Vector*" ![](../image/core/pokemini/Monochrome_Vector.png) - **Piezo Filter** [pokemini_piezofilter] (**ON**|OFF) Enables an audio filter to more accurately simulate the characteristics of the Pokémon Mini's piezoelectric speaker. - **Rumble Level (Screen + Controller)** [pokemini_rumblelvl] (**3**|2|1|0) Specifies the magnitude of the force feedback effect, both virtual ('screen shake') and physical ('controller rumble'). - **Controller Rumble** [pokemini_controller_rumble] (**ON**|OFF) Enables physical force feedback effect via controller rumble. - **Screen Shake** [pokemini_screen_shake] (**ON**|OFF) Enables virtual force feedback effect by 'shaking' the screen. This is helpful when using a controller without physical rumble support, since a number of games rely on force feedback to prompt user action. ## Rumble Rumble only works in the PokeMini core when - The content being ran has rumble support. - The frontend being used has rumble support. - The joypad device being used has rumble support. - The core option 'Rumble Level' is set to any value other than '0'. - The core option 'Controller Rumble' is set to 'ON'. !!! attention If physical rumble is not supported, it is recommended to set the core option 'Screen Shake' to 'ON'. ## Joypad | RetroPad Inputs | User 1 input descriptors | |---------------------------------------------|--------------------------| | ![](../image/retropad/retro_b.png) | B | | ![](../image/retropad/retro_select.png) | Power | | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | | ![](../image/retropad/retro_a.png) | A | | ![](../image/retropad/retro_l1.png) | Shake | | ![](../image/retropad/retro_r1.png) | C | ## Compatibility | Game | Issue | |----------------------|------------------------------------------------------------------| | Pokemon Pinball Mini | EEPROM saves do not function correctly - use save states instead | | Pokemon Race Mini | EEPROM saves do not function correctly - use save states instead | ## External Links - [Official PokeMini SourceForge Repository](https://sourceforge.net/projects/pokemini/) - [Libretro PokeMini Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/pokemini_libretro.info) - [Libretro PokeMini Github Repository](https://github.com/libretro/PokeMini) - [Report Libretro PokeMini Core Issues Here](https://github.com/libretro/PokeMini/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0IcaGNn2eEveCloqDgw0G31P) ================================================ FILE: docs/library/ppsspp.md ================================================ # Sony - PlayStation Portable (PPSSPP) ## Background A fast and portable PSP emulator written in C++. No BIOS file required to play, PPSSPP is an "HLE" emulator. Default settings balance good compatibility and speed. The PPSSPP core has been authored by - Henrik Hrydgard The PPSSPP core is licensed under - [GPLv2](https://github.com/hrydgard/ppsspp/blob/master/LICENSE.TXT) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Setup (Required!!) The PPSSPP core requires some helper files to be fully functional, including assets such as fonts and backgrounds that are required for memory card screens, and per-game settings that are loaded automatically for compatibility/bugfixing. In order to acquire PPSSPP's assets files and install them succcessfully, follow these steps: !!! info Lakka users do not need to follow these steps. Lakka image ships with the assets already included. Those assets are compatible with the version of the core provided in the Lakka image. Using not compatible assets may lead to unexpected results. ### Installing from the 'Core System Files Downloader' If your frontend version has `Main Menu > Online Updater > Core System Files Downloader` then that's the easiest solution. Just download 'PPSSPP.zip' from that menu and you're all done! ### Installing from the GitHub repo 1 . Create a directory named PPSSPP in RetroArch's System directory. ``` RetroArch/ └── system/ └── PPSSPP/ ``` Here's an example of what it should look like. ![](../image/core/ppsspp/directory.png) 2 . Visit [https://github.com/hrydgard/ppsspp](https://github.com/hrydgard/ppsspp) and download the repository. ![](../image/core/ppsspp/download.png) 3 . Extract ppsspp-master.zip 4 . Copy the contents of `ppsspp-master/assets` into 'system/PPSSPP' The end result should look like this. ![](../image/core/ppsspp/ppsspp_assets.png) !!! attention Don't like PPSSPP's replacement fonts? You can place the original PSP fonts in 'system/PPSSPP/flash0/font' ## Extensions Content that can be loaded by the PPSSPP core have the following file extensions: - .elf - .iso - .cso - .prx - .pbp - .chd RetroArch database(s) that are associated with the PPSSPP core: - [Sony - PlayStation Portable](https://github.com/libretro/libretro-database/blob/master/rdb/Sony%20-%20PlayStation%20Portable.rdb) ## Features Frontend-level settings or features that the PPSSPP core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✕ | | Native Cheats | ✔ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✔ | | Language | ✔ | | Crop Overscan | ✕ | | LEDs | ✕ | **Texture Replacement Packs** High-resolution texture packs can be used by extracting any archives and placing the contents into the frontend's 'saves' directory, in a directory under PSP/TEXTURES, named for the [game's ID code](https://www.scribd.com/document/515954071/PSP-Game-IDs). **Netplay** PPSSPP-libretro can utilize the same netplay services provided by the standalone PPSSPP application by entering the desired network address in the core options, under the 'network' category. See [the upstream documentation](https://github.com/hrydgard/ppsspp/wiki/How-to-play-multiplayer-games-with-PPSSPP) for further details on setup. ## Directories The PPSSPP core's library name is 'PPSSPP' The PPSSPP core saves/loads to/from these directories. **Frontend's Save directory** ``` . └── PSP/ ├── PPSSPP_STATE/ (Used to be the state directory, no longer used) ├── SAVEDATA/ (In-game saves) ├── flash0/ (Font override for real fonts dumped from PSP system) ├── Cheats/ (Internal Cheats directory, disabled by default) ├── GAME/ (DLC directory) ├── SYSTEM/ └── CACHE/ (Shader cache) └── TEXTURES/ └── [GAME_ID] (Extracted textures; enabled via core option) ``` **Frontend's State directory** | File | Description | |:--------:|:-----------:| | *.state# | State | ## Geometry and timing - The PPSSPP core's core provided FPS is 60 - The PPSSPP core's core provided sample rate is 44100 Hz - The PPSSPP core's base width is dependent on the 'Internal Resolution' core option - The PPSSPP core's base height is dependent on the 'Internal Resolution' core option - The PPSSPP core's max width is dependent on the 'Internal Resolution' core option - The PPSSPP core's max height is dependent on the 'Internal Resolution' core option - The PPSSPP core's core provided aspect ratio is 16/9 ## Language When the 'Language' core option is set to automatic, the default PPSSPP language setting will be pulled from RetroArch's Language setting. ## Nickname PPSSPP's default nickname setting is pulled from RetroArch's nickname setting. ## Internal Cheats Disabled by default. **To enable and allow the use of ini cheat files in save\PSP\Cheats, set the 'Internal Cheats Support' core option to enabled.** Cheats can be used to unlock 60fps in several 30fps games. Each code can be activated or disabled in the ini directly with _C1 in place of _C0 on the title line. [PPSSPP forums thread](http://forums.ppsspp.org/showthread.php?tid=3590) ## DLC DLCs need to be installed in the GAME directory. Create the GAME directory in the PSP directory and it should look like this. RetroArch\saves\PPSSPP\PSP\GAME\ ## Hardware Rendering - **OpenGL** PPSSPP's OpenGL renderer can be used by setting RetroArch's video driver to gl or glcore (where available). This renderer requires hardware that supports OpenGL/Open GL ES 2.0 or higher. It is an older, pre-Vulkan API, which is slower but with better compatibility. If you encounter problems with other APIs, try this one. - **Vulkan** PPSSPP's Vulkan renderer can be used by setting RetroArch's video driver to vulkan. This is the latest and fastest API currently. It is most recommended for demanding less of your CPU, thus being the fastest. - **D3D11** PPSSPP's Direct3D 11 renderer can be used by setting RetroArch's video driver to d3d11. In some cases Direct3D 11 may offer better performance than OpenGL, especially on integrated Intel graphics. ## Core options The PPSSPP core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. ### System - **CPU Core** [ppsspp_cpu_core] (**jit**|IR jit|interpreter) The jit setting enables the Dynamic Recomplier (Dynarec) for CPU emulation. The Dynarec is much faster than the interpreter setting and is the default, recommended mode for supported architectures. The interpreter setting enables the Interpreter for CPU emulation. The Interpreter is a very slow type of emulation and mostly useful for debug, but should work anywhere. The IR jit setting might be worth trying against games which are broken in the other two settings. - **Fast Memory** [ppsspp_fast_memory] (**enabled**|disabled) This option avoids some memory accesses by caching information, however a few games may have problems when this option is enabled, most run with no problem. - **Ignore Bad Memory Accesses** - **I/O Timing Method** - **Force Real Clock Sync** - **Locked CPU Speed** [ppsspp_locked_cpu_speed] (**off**|222MHz|266MHz|333MHz) Allows you to lock the internal CPU clock of the emulator (of the emulated CPU). Larger clocks can ensure a more stable performance in certain games that present problems even on a real PSP, but it requires more powerful hardware. Lower clocks can help weak hardware have more comfortable gameplay, limiting FPS to a lower rate. Changing this option opens the door to several bugs that may compromise some games. In case of doubt, keep this on off. - **Memory Stick Inserted** - **Cache Full ISO in RAM** - **Internal Cheats Support** [ppsspp_cheats] (**disabled**|enabled) Enables internal cheats. Look at the [Internal Cheats section](#internal-cheats) for more information. - **Game Language** [ppsspp_language] (**automatic**|english|japanese|french|spanish|german|italian|dutch|portuguese|russian|korean|chinese_traditional|chinese_simplified) Configure the PPSSPP's system language. When set to automatic, the default PPSSPP language setting will be pulled from RetroArch's Language setting. - **PSP Mode** ### Video - **Backend** [ppsspp_rendering_mode] (**Automatic**|OpenGL|Vulkan|D3D11|None) Sets the hardware rendering API. 'Automatic' uses whichever backend matches the frontend's current video driver. - **Software Rendering** - **Rendering Resolution** [ppsspp_internal_resolution] (**480x272**|960x544|1440x816|1920x1088|2400x1360|2880x1632|3360x1904|3840x2176|4320x2448|4800x2720) **The 'Software Rendering' core option must be set to OFF for this to have any effect.** Controls the internal resolution of the graphics, significant performance impact if your GPU is not powerful enough for certain resolutions. - **MSAA Antialiasing** - **Crop to 16x9** - **Frameskip** [ppsspp_frameskip] (**0**|1|2|3|4|5|6|7|8|9) This option skips image frames to increase the emulation speed. They can be skipped between 1 and 8 frames every second. Using this option can give the impression of the game running faster but with stuttering, and this increases the amount of frames to be skipped you select. This option is only effective when your processor is powerful enough. - **Auto Frameskip** [ppsspp_auto_frameskip] (**disabled**|enabled) This option only selects the optimal number of frames to skip to not to compromise both gameplay. The max frames to be skipped can be limited in the Frameskip option. - **Render Duplicate Frames to 60 Hz** - **Detect Frame Rate Changes** - **Buffer Graphics Commands** - **Software Skinning** - **Hardware Tesselation** - **Texture Upscale Type** [ppsspp_texture_scaling_type] (**xbrz**|hybrid|bicubic|hybrid_bicubic) Choose the Texture Upscale Type. xBRZ is overall the best option while Hybrid is a slower version of xBRZ and doesn't offers much difference, Hybrid + Bicubic is the slowest one using two effects. - **Texture Upscaling Level** [ppsspp_texture_scaling_level] (**1**|2|3|4|5|0) With this option, you can make modifications to the texture scale level, which improves the visual at high resolutions. All the scaling is made by CPU and results in a great performance impact. Use carefully. - **Texture Deposterize** [ppsspp_texture_deposterize] (**disabled**|enabled) Deposterize fixes small in-texture glitches that may happen when the texture is upscaled. - **Texture Shader** - **Anisotropic Filtering** [ppsspp_texture_anisotropic_filtering] (**off**|1x|2x|4x|8x|16x) Modify the Anisotropic Filtering, which fixes the textures on the horizon that are drawn at angles resulting in a better look. - **Texture Filtering** [ppsspp_texture_filtering] (**auto**|nearest|linear|linear(FMV)) Apply texture filtering. Stick to auto in case of doubt. - **Smart 2D Texture Filtering** - **Texture Replacement** ### Input - **Confirmation Button** [ppsspp_button_preference] (**cross**|circle) Select whether the cross input or the circle input is the confirmation button. - **Analog Circle vs Square Gate Compensation** - **Analog Deadzone** Additional deadzone to apply after frontend input. - **Analog Axis Scale** Additional sensitivity to apply after frontend input. ### Hacks - **Skip Buffer Effects** Faster, but nothing may draw in some games. - **Disable Culling** - **Skip GPU Readbacks** Some games require GPU readbacks, so be careful. - **Lazy Texture Caching (Speedup)** Faster, but can cause text problems in a few games. - **Spline/Bezier Curves Quality** Only used by some games, controls smoothness of curves. - **Lower Resolution for Effects** Reduces artifacts ### Network - **Enable Networking/WLAN (Beta, may break games)** - **MAC Address Pt 1: x-:--:--:--:--:--** - **MAC Address Pt 2: -x:--:--:--:--:--** - **MAC Address Pt 3: --:x-:--:--:--:--** - **MAC Address Pt 4: --:-x:--:--:--:--** - **MAC Address Pt 5: --:--:x-:--:--:--** - **MAC Address Pt 6: --:--:-x:--:--:--** - **MAC Address Pt 7: --:--:--:x-:--:--** - **MAC Address Pt 8: --:--:--:-x:--:--** - **MAC Address Pt 9: --:--:--:--:x-:--** - **MAC Address Pt 10: --:--:--:--:-x:--** - **MAC Address Pt 11: --:--:--:--:--:x-** - **MAC Address Pt 12: --:--:--:--:--:-x** - **WLAN Channel** - **Enable Built-in PRO Ad Hoc Server** - **Change PRO Ad Hoc Server IP Address ('localhost' = multiple instances)** - **Enable UPnP (Need a few seconds to detect)** - **Port Offset ('0' = PSP Compatibility)** - **Minimum Timeout (Override in ms, '0' = default)** - **Forced First Connect (Faster connect)** ## Joypad ![](../image/controller/psp.png) | RetroPad Inputs | User 1 input descriptors | |------------------------------------------------|--------------------------| | ![](../image/retropad/retro_b.png) | Cross | | ![](../image/retropad/retro_y.png) | Square | | ![](../image/retropad/retro_select.png) | Select | | ![](../image/retropad/retro_start.png) | Start | | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | | ![](../image/retropad/retro_a.png) | Circle | | ![](../image/retropad/retro_x.png) | Triangle | | ![](../image/retropad/retro_l1.png) | L | | ![](../image/retropad/retro_r1.png) | R | | ![](../image/retropad/retro_left_stick.png) X | Analog X | | ![](../image/retropad/retro_left_stick.png) Y | Analog Y | ## Compatibility - [PPSSPP Compatibility List](http://report.ppsspp.org/games) ## External Links - [Official PPSSPP Website](http://www.ppsspp.org/) - [Official PPSSPP Github Repository](https://github.com/hrydgard/ppsspp) - [Libretro PPSSPP Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/ppsspp_libretro.info) - [Report Libretro PPSSPP Core Issues Here](https://github.com/libretro/ppsspp/issues) - [Gameplay Videos](https://www.youtube.com/playlist?list=PLRbgg4gk_0IcjmP26m8-3JWNzYUXRjqWT) ================================================ FILE: docs/library/prboom.md ================================================ # Doom (PrBoom) ## Background Port of prboom to libretro - plays Doom, Doom II, Final Doom and other Doom IWAD mods. The PrBoom core has been authored by - Florian Schulze The PrBoom core is licensed under - [GPLv2](https://github.com/libretro/libretro-prboom/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | |:--------------------------------------------------------------------------------:|:---------------------:| | [prboom.wad](https://github.com/libretro/libretro-prboom/blob/master/prboom.wad) | PrBoom requires data ROM 'prboom.wad' inside the SYSTEM directory. | ## Extensions Content that can be loaded by the PrBoom core have the following file extensions: - .wad - .iwad - .pwad RetroArch database(s) that are associated with the PrBoom core: - [DOOM](https://github.com/libretro/libretro-database/blob/master/rdb/DOOM.rdb) ## Features Frontend-level settings or features that the PrBoom core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✕ | | Rewind | ✕ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | | RetroArch Cheats | ✔ | | Native Cheats | ✔ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The PrBoom core's library name is 'PrBoom' The PrBoom core saves/loads to/from these directories. **Frontend's Save directory** | File | Description | |:-------------------------:|:-----------:| | (content name)/*.dsg | Save | | (content name)/prboom.cfg | DOOM Config | ### Geometry and timing - The PrBoom core's core provided FPS (by default) is 60 - The PrBoom core's core provided sample rate is 44100 Hz - The PrBoom core's base width is dependent on the Internal resolution core option. - The PrBoom core's base height is dependent on the Internal resolution core option. - The PrBoom core's max width is dependent on the Internal resolution core option. - The PrBoom core's max height is dependent on the Internal resolution core option. - The PrBoom core's core provided aspect ratio is 4/3 ## Loading DOOM PrBoom can load wad, iwad, and pwad files. The PrBoom core requires data ROM ['prboom.wad'](https://github.com/libretro/libretro-prboom/blob/master/prboom.wad) inside the loaded content's or system directory. !!! TIP If you start the games by loading prboom.wad they will all share the same content name ("prboom" in this case), so the core will put the saves for every game in a single retroarch/saves/prboom/ folder and when playing Doom 2 for example you'll see Doom 1 saves, etc. which will cause confusion for the user. The games will also share the same game overrides/options files/remaps/etc. History tab will also lists each game as "prboom". An example folder structure would be like so: ``` └── contents/ └── dooms/ ├── doom/ │ ├── doom.wad │ └── [music_files].mp3 └── doom2/ ├── doom2.wad └── [music_files].mp3 ``` ``` └── retroarch/ └── system └── prboom.wad ``` Game saves and internal configuration files will be created in the frontend-defined save directory, organised in folders matching the filenames of loaded content - for example: ``` └── saves/ └── PrBoom/ ├── doom/ │ ├── prbmsav0.dsg │ ├── prbmsav1.dsg │ └── prboom.cfg └── doom2/ ├── prbmsav0.dsg ├── prbmsav1.dsg └── prboom.cfg ``` Game saves are numbered from 'prbmsav0.dsg' to 'prbmsav7.dsg'. ## SIGIL Sigil (stylized as SIGIL) is the unofficial fifth episode of the 1993 video game Doom. Published by Romero Games on May 31, 2019, the Megawad was created by an original co-creator of Doom, John Romero, independently of the main game's then-current owner, Bethesda Softworks. It has nine missions, each with a deathmatch version, and a new soundtrack created by James Paddock and Buckethead. You can get SIGIL [here](https://romero.com/) Turn off 'Look on parent folders for IWADs' inside Quick Menu - Options. This is usually enabled by default, so disable it. Make sure that you place the SIGIL wad files inside the same directory as your Doom/Ultimate Doom WAD file. You can name this either doomu.wad or doom.wad. Make sure there are NO doom2.wad files inside this same directory, or Sigil might not work properly. An example folder structure would be like so: ``` └── contents/ └── dooms/ └── doom/ ├── doom.wad ├── SIGIL.WAD └── [music_files].mp3 ``` ``` └── retroarch/ └── system/ └── prboom.wad ``` ## Music If mp3 files are detected in the game folder, PrBoom will play these tracks instead of the internal MIDI musics, see below for the required filenames for each game. ### Doom !!! Note Episode 4 doesn't have exclusive musics, it uses tracks from the previous episodes. | Filename | Description | |------------|--------------------| | bunny.mp3 | Endgame Music | | e1m1.mp3 | E1M1 | | e1m2.mp3 | E1M2 | | e1m3.mp3 | E1M3 | | e1m4.mp3 | E1M4 | | e1m5.mp3 | E1M5 | | e1m6.mp3 | E1M6 | | e1m7.mp3 | E1M7 | | e1m8.mp3 | E1M8 | | e1m9.mp3 | E1M9 | | e2m1.mp3 | E2M1 | | e2m2.mp3 | E2M2 | | e2m3.mp3 | E2M3 | | e2m4.mp3 | E2M4 | | e2m5.mp3 | E2M5 | | e2m6.mp3 | E2M6 | | e2m7.mp3 | E2M7 | | e2m8.mp3 | E2M8 | | e2m9.mp3 | E2M9 | | e3m1.mp3 | E3M1 | | e3m2.mp3 | E3M2 | | e3m3.mp3 | E3M3 | | e3m4.mp3 | E3M4 | | e3m5.mp3 | E3M5 | | e3m6.mp3 | E3M6 | | e3m7.mp3 | E3M7 | | e3m8.mp3 | E3M8 | | e3m9.mp3 | E3M9 | | inter.mp3 | Intermission Music | | intro.mp3 | Title Music | | victor.mp3 | Victory Music | ### Doom II, Plutonia, TNT !!! Note These 3 games share the same music filenames but the musics are actually different, for this reason it is recommended to have the games in separated folders. | Filename | Description | |------------|--------------------| | adrian.mp3 | MAP25 | | ampie.mp3 | MAP23 | | betwee.mp3 | MAP04 | | count2.mp3 | MAP21 | | countd.mp3 | MAP03 | | ddtbl2.mp3 | MAP14 | | ddtbl3.mp3 | MAP22 | | ddtblu.mp3 | MAP08 | | dead.mp3 | MAP10 | | dead2.mp3 | MAP16 | | dm2int.mp3 | Intermission Music | | dm2ttl.mp3 | Title Music | | doom.mp3 | MAP05 | | doom2.mp3 | MAP13 | | evil.mp3 | MAP31 | | in_cit.mp3 | MAP09 | | messag.mp3 | MAP20 | | messg2.mp3 | MAP26 | | openin.mp3 | MAP30 | | read_m.mp3 | Endgame Music | | romer2.mp3 | MAP27 | | romero.mp3 | MAP18 | | runni2.mp3 | MAP15 | | runnin.mp3 | MAP01 | | shawn.mp3 | MAP07 | | shawn2.mp3 | MAP19 | | shawn3.mp3 | MAP29 | | stalks.mp3 | MAP02 | | stlks2.mp3 | MAP11 | | stlks3.mp3 | MAP17 | | tense.mp3 | MAP28 | | theda2.mp3 | MAP12 | | theda3.mp3 | MAP24 | | the_da.mp3 | MAP06 | | ultima.mp3 | MAP32 | ### SIGIL | Filename | Description | |------------|--------------------| | e5m1.mp3 | E5M1 | | e5m2.mp3 | E5M2 | | e5m3.mp3 | E5M3 | | e5m4.mp3 | E5M4 | | e5m5.mp3 | E5M5 | | e5m6.mp3 | E5M6 | | e5m7.mp3 | E5M7 | | e5m8.mp3 | E5M8 | | e5m9.mp3 | E5M9 | | inter.mp3 | Intermission Music | | intro.mp3 | Title Music | ## Config PrBoom's internal game settings can be found in the 'prboom.cfg' file inside each game's save directory. Many of these settings may be changed from the in-game menu. A few notable options are as follows: - Options → General (page 1) → Framerate (35fps|40fps|50fps|**60fps**|70fps|72fps|75fps|90fps|100fps| 119fps|120fps|140fps|144fps|240fps|244fps) Vanilla Doom has a native framerate of 35fps. This should be considered the 'correct' value, but it can lead to an irregular 'stuttering' effect on 60Hz LCD displays. All framerates should maintain the proper game speed. - Options → General (page 1) → Gamma Correction (**Off**|Lv. 1|Lv. 2|Lv. 3|Lv. 4) Sets display brightness. - Options → Screen Size (**Low**|High) When set to 'Low', the HUD is shown at the bottom of the screen. When set to 'High', the gameplay area fills the screen and no HUD is shown. - Options → Mouse Sensitivity The 'horizontal' slider sets the movement speed when looking left/right with either the mouse or the gamepad right analog stick. ## Core options The PrBoom core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch. - **Internal resolution (restart)** [prboom-resolution] (**320x200**|640x400|960x600|1280x800|1600x1000|1920x1200) Configure the resolution. Requires a restart. ??? note "Internal resolution - 320x200" ![](../image/core/prboom/320x200.png) ??? note "Internal resolution - 1920x1200" ![](../image/core/prboom/1920x1200.png) - **Mouse active when using Gamepad** [prboom-mouse_on] (**disabled**|enabled) Allows you to use mouse inputs even when User 1's device type isn't set to 'RetroKeyboard/Mouse'. - **Look on parent folders for IWADs** [prboom-find_recursive_on] (**enabled**|disabled) Scans parent folders for IWADs. NOTE: You need to disable this if you want to run SIGIL. - **Analog Deadzone (percent)** [prboom-analog_deadzone] (**15**|20|25|30|0|5|10) Sets the deadzone of the Gamepad analog sticks when the input device type is set to 'Gamepad Modern'. ## User 1 device types The PrBoom core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): - None - Input disabled. - **Gamepad Classic** - Joypad - **Gamepad Modern** - Joypad - **RetroKeyboard/Mouse** - Keyboard and Mouse - Switch to this for keyboard and mouse input. Has keymapper support. ## Joypad | User 1 input descriptors for 'Gamepad Classic' device type | RetroPad Inputs | PrBoom inputs | |------------------------------------------------------------|---------------------------------------------|-----------------| | Use | ![](../image/retropad/retro_b.png) | Use | | Run | ![](../image/retropad/retro_y.png) | Run | | Show/Hide Map | ![](../image/retropad/retro_select.png) | Show/Hide Map | | Show/Hide Menu | ![](../image/retropad/retro_start.png) | Show/Hide Menu | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | | Fire | ![](../image/retropad/retro_a.png) | Fire | | Strafe | ![](../image/retropad/retro_x.png) | Strafe | | Strafe Left | ![](../image/retropad/retro_l1.png) | Strafe Left | | Strafe Right | ![](../image/retropad/retro_r1.png) | Strafe Right | | Previous Weapon | ![](../image/retropad/retro_l2.png) | Previous Weapon | | Next Weapon | ![](../image/retropad/retro_r2.png) | Next Weapon | | User 1 input descriptors for 'Gamepad Modern' device type | RetroPad Inputs | PrBoom inputs | |-----------------------------------------------------------|------------------------------------------------|-------------------------| | Menu Cancel | ![](../image/retropad/retro_b.png) | Menu Cancel | | Quick Save | ![](../image/retropad/retro_y.png) | Quick Save | | Show/Hide Map | ![](../image/retropad/retro_select.png) | Show/Hide Map | | Show/Hide Menu | ![](../image/retropad/retro_start.png) | Show/Hide Menu | | D-Pad Up | ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | | D-Pad Down | ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | | D-Pad Left | ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | | D-Pad Right | ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | | Menu Select | ![](../image/retropad/retro_a.png) | Menu Select | | Quick Load | ![](../image/retropad/retro_x.png) | Quick Load | | Previous Weapon | ![](../image/retropad/retro_l1.png) | Previous Weapon | | Next Weapon | ![](../image/retropad/retro_r1.png) | Next Weapon | | Use | ![](../image/retropad/retro_l2.png) | Use | | Fire | ![](../image/retropad/retro_r2.png) | Fire | | Toggle Run | ![](../image/retropad/retro_l3.png) | Toggle Run | | 180 Turn | ![](../image/retropad/retro_r3.png) | 180 Turn | | | ![](../image/retropad/retro_left_stick.png) X | Strafe Left/Right | | | ![](../image/retropad/retro_left_stick.png) Y | Move Forwards/Backwards | | | ![](../image/retropad/retro_right_stick.png) X | Look Left/Right | ## Keyboard and Mouse | RetroKeyboard/Mouse inputs | Weapons | |-------------------------------------------------|-----------------| | Keyboard 1 | Fist | | Keyboard 2 | Pistol | | Keyboard 3 | Shotgun | | Keyboard 4 | Chaingun | | Keyboard 5 | Rocket | | Keyboard 8 | Chainsaw | | Keyboard 0 | Best | | Keyboard Left Control | Fire | | Keyboard Right Control | Fire | | Wheel Up | Next Weapon | | Wheel Down | Previous Weapon | | ![](../image/retromouse/retro_left.png) Mouse 1 | Fire | | RetroKeyboard/Mouse inputs | Movement | |-------------------------------------------------------|-----------------| | Keyboard Up | Forward | | Keyboard Down | Backward | | Keyboard Left | Turn Left | | Keyboard Right | Turn Right | | Keyboard Left Shift | Run | | Keyboard Right Shift | Run | | Keyboard Less than < | Strafe Left | | Keyboard Greater than > | Strafe Right | | Keyboard Left Alt | Strafe | | Keyboard Right Alt | Strafe | | Keyboard Caps Lock | Autorun | | Keyboard Slash / | 180 Turn | | Keyboard Space | Use | | ![](../image/retromouse/retro_mouse.png) Mouse Cursor | Turn Left/Right | | ![](../image/retromouse/retro_right.png) Mouse 2 | Strafe | | ![](../image/retromouse/retro_middle.png) Mouse 3 | Use | | ![](../image/retromouse/retro_middle.png) Mouse 3 | Forward | | RetroKeyboard/Mouse inputs | Game | |----------------------------|-----------| | Keyboard F2 | Save | | Keyboard F3 | Load | | Keyboard F6 | Quicksave | | Keyboard F7 | Endgame | | Keyboard F9 | Quickload | | Keyboard F10 | Quit | | RetroKeyboard/Mouse inputs | Screen | |------------------------------|--------------| | Keyboard F1 | Help | | Keyboard Escape | Menu | | Keyboard Home | Setup | | Keyboard Pause | Pause | | Keyboard Tab | Automap | | Keyboard F4 | Sound Volume | | Keyboard F5 | HUD | | Keyboard F8 | Messages | | Keyboard F11 | Gamma Fix | | Keyboard F12 | Spy | | Keyboard Minus - | Smaller View | | Keyboard Plus + | Larger View | | RetroKeyboard/Mouse inputs | Automap | |----------------------------|-------------| | Keyboard f | Follow Mode | | Keyboard Minus - | Zoom in | | Keyboard Plus + | Zoom out | | Keyboard m | Mark Place | | Keyboard c | Clear Marks | | Keyboard o | Full/Zoom | | Keyboard g | Grid | ## External Links - [Official PrBoom Website](http://prboom.sourceforge.net/) - [Official PrBoom SourceForge Repository](http://sourceforge.net/projects/prboom/) - [Libretro PrBoom Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/prboom_libretro.info) - [Libretro PrBoom Github Repository](https://github.com/libretro/libretro-prboom) - [Report Libretro PrBoom Core Issues Here](https://github.com/libretro/libretro-prboom/issues) ## id Software - [Quake 1 (TyrQuake)](tyrquake.md) ================================================ FILE: docs/library/prosystem.md ================================================ # Atari - 7800 (ProSystem) ## Background ProSystem is an Atari 7800 emulator. ### Author/License The ProSystem core has been authored by - Greg Stanton - Brian Berlin - Leonis - Greg DeMent The ProSystem core is licensed under - [GPLv2](https://github.com/libretro/prosystem-libretro/blob/master/License.txt) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the ProSystem core have the following file extensions: - .a78 - .bin ## Databases RetroArch database(s) that are associated with the ProSystem core: - [Atari - 7800](https://github.com/libretro/libretro-database/blob/master/rdb/Atari%20-%207800.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. | Filename | Description | md5sum | |:-----------------:|:--------------------:|:--------------------------------:| | 7800 BIOS (U).rom | 7800 BIOS - Optional | 0763f1ffb006ddbe32e52d497ee848ae | ## Features Frontend-level settings or features that the ProSystem core respects. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✕ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✕ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✕ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✕ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✕ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✕ | ### Directories The ProSystem core's internal core name is 'ProSystem' The ProSystem core saves/loads to/from these directories. **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The ProSystem core's core provided FPS is 60 for NTSC games and 50 for PAL games. - The ProSystem core's core provided sample rate is 32640 Hz for NTSC games and 31200 Hz for PAL games - The ProSystem core's core provided base width is 320 - The ProSystem core's core provided base height is 223 for NTSC games and 272 for PAL games - The ProSystem core's core provided max width is 320 - The ProSystem core's core provided max height is 292 - The ProSystem core's core provided aspect ratio is 4/3 ## Controllers The ProSystem core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): ### User 1 - 2 device types - None - Doesn't disable input. There's no reason to switch to this. - **RetroPad** - Joypad - Stay on this. - RetroPad w/Analog - Joypad - Same as RetroPad. There's no reaosn to switch to this. ### Controller tables #### Joypad ![](../image/controller/atari_7800.png) | User 1 Remap descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | B | ![](../image/retropad/retro_b.png) | | Console Select | ![](../image/retropad/retro_select.png) | | Console Pause | ![](../image/retropad/retro_start.png) | | Up | ![](../image/retropad/retro_dpad_up.png) | | Down | ![](../image/retropad/retro_dpad_down.png) | | Left | ![](../image/retropad/retro_dpad_left.png) | | Right | ![](../image/retropad/retro_dpad_right.png) | | 2 | ![](../image/retropad/retro_a.png) | | Console Reset | ![](../image/retropad/retro_x.png) | | Left Difficulty | ![](../image/retropad/retro_l1.png) | | Right Difficulty | ![](../image/retropad/retro_r1.png) | | User 2 Remap descriptors | RetroPad Inputs | |--------------------------|---------------------------------------------| | 1 | ![](../image/retropad/retro_b.png) | | Up | ![](../image/retropad/retro_dpad_up.png) | | Down | ![](../image/retropad/retro_dpad_down.png) | | Left | ![](../image/retropad/retro_dpad_left.png) | | Right | ![](../image/retropad/retro_dpad_right.png) | | 2 | ![](../image/retropad/retro_a.png) | ## External Links - [Official ProSystem Website](https://gstanton.github.io/ProSystem1_3/) - [Official ProSystem Github Repository](https://github.com/gstanton/ProSystem1_3) - [Libretro ProSystem Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/prosystem_libretro.info) - [Libretro ProSystem Github Repository](https://github.com/libretro/prosystem-libretro) - [Report Libretro ProSystem Core Issues Here](https://github.com/libretro/prosystem-libretro/issues) ================================================ FILE: docs/library/puae.md ================================================ # PUAE ## Background PUAE tries to continue where E-UAE left off. PUAE versioning is based on the merged WinUAE version. The PUAE core have been authored by - UAE Team The PUAE core is licensed under - [GPLv2](https://github.com/libretro/libretro-uae/blob/master/COPYING) A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). ## Extensions Content that can be loaded by the PUAE core have the following file extensions: ### Floppies - .adf - .adz - .dms - .fdi - .ipf - .raw ### Hard drives - .hdf - .hdz - directory ### WHDLoad - .lha - .slave - .info ### Compact discs - .cue - .ccd - .chd - .nrg - .mds - .iso ### Other - .uae - .m3u - .zip - .7z ## Databases RetroArch database(s) that are associated with the PUAE core: - [Commodore - Amiga](https://github.com/libretro/libretro-database/blob/master/rdb/Commodore%20-%20Amiga.rdb) ## BIOS Required or optional firmware files go in the frontend's system directory. The core has a somewhat compatible built-in AROS Kickstart, which is used as a fallback when the proper Kickstart is not found. Amiga Forever and TOSEC filenames are also accepted. | Filename | Amiga Forever | Description | md5sum | |--------------------|---------------------------|------------------------------------|----------------------------------| | kick31034.A1000 | amiga-os-110-ntsc.rom | Kickstart v1.1 rev 31.034 NTSC | 0b8442c311caa54fb12ec88eaaa9facf | | kick32034.A1000 | amiga-os-110-pal.rom | Kickstart v1.1 rev 32.034 PAL | 1fa1f93d3d7b51271dd1356b8b2b45a9 | | kick33180.A500 | amiga-os-120.rom | Kickstart v1.2 rev 33.180 | 85ad74194e87c08904327de1a9443b7a | | kick34005.A500 | amiga-os-130.rom | Kickstart v1.3 rev 34.005 | 82a21c1890cae844b3df741f2762d48d | | kick37175.A500 | amiga-os-204.rom | Kickstart v2.04 rev 37.175 | dc10d7bdd1b6f450773dfb558477c230 | | kick37350.A600 | amiga-os-205-a600.rom | Kickstart v2.05 rev 37.350 | 465646c9b6729f77eea5314d1f057951 | | kick40063.A600 | amiga-os-310-a600.rom | Kickstart v3.1 rev 40.063 | e40a5dfb3d017ba8779faba30cbd1c8e | | kick39106.A1200 | amiga-os-300-a1200.rom | Kickstart v3.0 rev 39.106 | b7cc148386aa631136f510cd29e42fc3 | | kick40068.A1200 | amiga-os-310-a1200.rom | Kickstart v3.1 rev 40.068 | 646773759326fbac3b2311fd8c8793ee | | kick39106.A4000 | amiga-os-300-a4000.rom | Kickstart v3.0 rev 39.106 | 9b8bdd5a3fd32c2a5a6f5b1aefc799a5 | | kick40068.A4000 | amiga-os-310-a4000.rom | Kickstart v3.1 rev 40.068 | 9bdedde6a4f33555b4a270c8ca53297d | | kick34005.CDTV | amiga-os-130-cdtv-ext.rom | CDTV extended ROM v1.00 | 89da1838a24460e4b93f4f0c5d92d48d | | kick40060.CD32 | amiga-os-310-cd32.rom | CD32 Kickstart v3.1 rev 40.060 | 5f8924d013dd57a89cf349f4cdedc6b1 | | kick40060.CD32.ext | amiga-os-310-cd32-ext.rom | CD32 extended ROM rev 40.060 | bb72565701b1b6faece07d68ea5da639 | | kick40060.CD32 | | CD32 KS + extended v3.1 rev 40.060 | f2f241bf094168cfb9e7805dc2856433 | ## Features Frontend-level settings or features that the PUAE core respect. | Feature | Supported | |-------------------|:---------:| | Restart | ✔ | | Screenshots | ✔ | | Saves | ✔ | | States | ✔ | | Rewind | ✔ | | Netplay | ✕ | | Core Options | ✔ | | [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✔ | | RetroArch Cheats | ✔ | | Native Cheats | ✕ | | Controls | ✔ | | Remapping | ✔ | | Multi-Mouse | ✔ | | Rumble | ✕ | | Sensors | ✕ | | Camera | ✕ | | Location | ✕ | | Subsystem | ✕ | | [Softpatching](../guides/softpatching.md) | ✕ | | Disk Control | ✔ | | Username | ✕ | | Language | ✕ | | Crop Overscan | ✕ | | LEDs | ✔ | ### Directories The PUAE core's internal core name is 'puae'. The PUAE core saves/loads to/from these directories. **Frontend's Save directory** - 'content-name'.nvr (CD32/CDTV NVRAM) - `BootHD`/`puae_libretro.hdf` (Optional global boot hard drive image directory/file) - `WHDLoad`/`WHDLoad.hdf` (WHDLoad helper image directory/file) - `WHDSaves`/`WHDSaves.hdf` (WHDLoad save image directory/file) **Frontend's State directory** - 'content-name'.state# (State) ### Geometry and timing - The PUAE core's core provided FPS is dynamic, but initially by default 50 for PAL and 59.94 for NTSC - The PUAE core's core provided sample rate is 44100 Hz - The PUAE core's base width is 360 in LoRes, 720 in HiRes 1440 in SuperHires - The PUAE core's base height is 288 for PAL single line, 576 for PAL double line, 240 for NTSC single line, 480 for NTSC double line - The PUAE core's max width is 1440 - The PUAE core's max height is 576 - The PUAE core's core provided aspect ratio is automatically set based on core options ### M3U and Disk control When you have a multi disk game, you can use a M3U playlist file to be able to change disks via RetroArch Disc Control interface. A M3U file is a simple text file with one disk per line ([Wikipedia](https://en.wikipedia.org/wiki/M3U)). Example: `Simpsons, The - Bart vs. The Space Mutants.m3u` ``` Simpsons, The - Bart vs. The Space Mutants_Disk1.adf Simpsons, The - Bart vs. The Space Mutants_Disk2.adf ``` Path can be absolute or relative to the location of the M3U file. When the game asks for it, you can change the current disk in the RetroArch "Disc Control" menu: - Eject the current disk with "Eject Disc" - Select the right disk index with "Current Disc Index" - Insert the new disk with "Insert Disc" For games that support multiple disk drives, append "**(MD)**" as in "MultiDrive" to the M3U filename to insert each disk in different drives. Only possible with maximum 4 disks! ***MultiDrive option is enabled by default, so the tag is not necessary, but some games require disabling it, because they can't handle multiple disk drives.*** For games that require a dedicated save disk, one may be generated automatically by entering the following line in an M3U file: `#SAVEDISK:VolumeName`. `VolumeName` is optional and may be omitted. For example, this will create a blank, unlabelled disk image at disk index 5: `Secret of Monkey Island.m3u` ``` Secret of Monkey Island_Disk 1.adf Secret of Monkey Island_Disk 2.adf Secret of Monkey Island_Disk 3.adf Secret of Monkey Island_Disk 4.adf #SAVEDISK: ``` Some games require save disks to have a specific label - for example, `It Came from the Desert` will only save to a disk named `DSAVE`: `It Came from the Desert.m3u` ``` It Came from the Desert_Disk 1.adf It Came from the Desert_Disk 2.adf It Came from the Desert_Disk 3.adf #SAVEDISK:DSAVE ``` Although one save disk is normally sufficient, an arbitrary number of `#SAVEDISK:VolumeName` lines may be included. Save disks are located in the frontend's save directory, with the following name: `[M3U_FILE_NAME].save[DISK_INDEX].adf`. By default, RetroArch will display the filename (without extension) of each M3U entry when selecting a disk via the `Current Disc Index` drop-down menu. Custom display labels may be set for each disk using the syntax: `DISK_FILE|DISK_LABEL`. For example, the following M3U file: `Valhalla & the Fortress of Eve.m3u` ``` Valhalla & the Fortress of Eve_Disk1.adf|Game Disk Valhalla & the Fortress of Eve_Disk2.adf|Data Disk Valhalla & the Fortress of Eve_Disk3.adf|Level 1 Disk Valhalla & the Fortress of Eve_Disk4.adf|Level 2 Disk Valhalla & the Fortress of Eve_Disk5.adf|Level 3 Disk Valhalla & the Fortress of Eve_Disk6.adf|Level 4 Disk ``` ...will be shown in RetroArch's disk selection menu as: ``` 1: Game Disk 2: Data Disk 3: Level 1 Disk 4: Level 2 Disk 5: Level 3 Disk 6: Level 4 Disk ``` If `DISK_LABEL` is intentionally left blank (i.e. `DISK_FILE|`) then only the disk index will be displayed. Save disks generated by the `#SAVEDISK:` keyword are automatically assigned the label: `Save Disk [SAVE_DISK_INDEX]`. #### Extra M3U features - `#SAVEDISK: