5. FAQ - zach-morris/plugin.program.iagl GitHub Wiki

1. What is this??!?!?

It's an addon for your HTPC running Kodi, so that you can play retro games.... Which games you ask?

Some of the available Platforms are:

  • 3DO
  • Amiga
  • Amiga CD32
  • Amstrad CPC
  • Arcade
  • Atari 2600
  • Atari 5200
  • Atari 7800
  • Atari 800
  • Atari Jaguar
  • Atari Lynx
  • Atari ST
  • ColecoVision
  • Commodore 64
  • Game Boy
  • Game Boy Advance
  • Game Boy Color
  • Gamecube
  • Game Gear
  • Game and Watch
  • Intellivision
  • Karaoke
  • MS-DOS
  • MS-Windows
  • MSX
  • Magnavox Odyssey 2
  • N64
  • NES
  • Neo Geo CD
  • Neo Geo Pocket
  • NDS
  • Pokemon Mini
  • PCE CD, TurboGrafx CD
  • PCE SuperGrafx
  • PCE, TurboGrafx 16
  • Philips CD-i
  • Playstation
  • Playstation Portable
  • SNES
  • Satellaview
  • Scumm VM
  • Sega 32X
  • Sega CD
  • Sega Dreamcast
  • Sega Genesis
  • Sega Master System
  • Sega SG-1000
  • Sega Saturn
  • Standalone Game
  • Vectrex
  • Virtual Boy
  • Wii
  • WonderSwan
  • WonderSwan Color
  • ZX Spectrum

It's currently over 10TB of games!!! Way too many to count...

2. Where are the games downloaded to?

IAGL uses a temporary cache folder in the Kodi userdata folder by default (folder is named 'game_cache'). ..path_to_userdata/addon_data/plugin.program.iagl/game_cache

You can change the cache folder size in the addon settings.

The cache size is by default set to Zero, meaning the addon will not keep the files. You can increase the cache size to something bigger. What you choose depends on what kind of games you play and how often you play them. Atari games for example are just a few kb. CD based systems are easily over 500MB per game.

If you don't want the files for a particular game to be deleted and want them available for 'instant launching', you can change the download location. You can mix and match which games are cached and which are saved to alternate locations on a per-archive basis.

To modify the download location:

  • Highlight the game archive of interest
  • Bring up the context menu (right click or press c)
  • Choose 'Update Download Path' and follow the prompts

Note that the addon does not monitor the size your alternate save folder, so you will have to manually manage any files not saved in the default folder.

If you are using an Android OS and want to change the download location to an external storage device, see here.

3. I want to use emulator XXX instead!

No problemo, IAGL is setup to support external emulators. By default, IAGL is shipped with external commands to support Retroarch and a few choice others. If your emulator of choice isn't listed, you can provide your own command line. To do that:

  • Highlight the game archive of interest
  • Bring up the context menu (right click or press c)
  • Choose 'Update External Launch Command'
  • Choose the bottom option, "Manually entered command line". Then simply enter the command into the prompt just as you would on the command line. You can also use the variables in your command. The variables you can use to support launching:

%ROM_PATH% - The addon will automatically replace this with the full path to the Game after it's downloaded.

%APP_PATH% - The addon will automatically replace this with the addon setting 'Retroarch Executable'

%ADDON_DIR% - The addon will automatically replace this with the addon's installation directory. This is typically used in conjunction with 'helper scripts' that are located in the addon bin directory, so a typical usage would be something like: %ADDON_DIR%/resources/bin/helper_script_filename.sh

Take a look at the commands listed here to get an idea of what your command should look like.

If you've got a sweet launcher command you've made, let me know so I can add it to the default list provided in the next update.

4. I want you to add game system XXX to IAGL!

OK. Go here here, and include a note with some info on what you are interested in, along with an essay and TPS report in triplicate. There are no guarantees that I'll add it.

5. What is CHDMAN?

Some game archives are in Compressed Hunks of Data (CHD) format. In order to use CHD archives, a helper application provided by MAME / MESS called CHDMAN is required. CHDMAN is packaged with MAME / MESS. The utility converts the CHD file to a usable format supported by Retroplayer / Retroarch (typically bin/cue). CHD archives typically contain the large games that are in ISO or BIN/CUE format. The CHDMAN binary is included in the addon for as many OS's as possible.

Retroarch cores have been updated to include support for CHD's natively, this is no longer required for any IAGL game lists.

6. What are MAME Softlists?

Some (non-arcade) old-school systems work with MESS and/or MAME. These sytems include (but are not limited to):

  • Vectrex
  • Neo Geo CD
  • Phillips CD-i
  • Atari 5200

Softlists allow Retroarch / MAME to load the game software based on some information in a "HASH" database. More information can be found here. Suffice to say, it's complicated to setup MAME (which now includes MESS) to play other non-arcade systems out of the box. IAGL sets out to automate all that stuff for you so you dont have to worry about it.

7. I don't want the addon to show XXX archive.

No problem. Just select the archive you don't want to see, then bring up the context menu (right click or press C) and select 'Update Visibility'.

8. Wait wait, I guess I do want to see that archive after all!

Make up your mind! OK. Now go into advanced addon settings and select "Unhide all archives". And yes, you'll have to re-hide archives after you select this.

9. What kind of game lists does IAGL include?

IAGL includes several archives from the internet archive as defaults. The default lists are typically unfiltered from the full list available on the internet archive to give you full access to retro gaming history. However, that often means many game lists appear to have lots of versions of the same game (Rev A, Rev B, European vs. USA version, etc), and in addition you could potentially have to scroll through all 200 mahjong games available, including the never released ultra-rare prototype version with different colored pokemon cards (OMG they're SILVER now!). If this isn't your cup of tea, you can typically filter games by 'custom groups', which allows you to easily get to a '1 Game / 1 Rom' type set, in addition to custom groups of most popular, best games for gamepads, etc. If there's a custom list you have that you'd like to include you can request it here

10. Can I manually edit the games lists?

Yes. The lists are just simple xml files. They are located in your userdata folder: ..path_to_userdata/addon_data/plugin.program.iagl/dat_files

See info here on the xml file format.

If you've edited an existing list, you'll need to select "Refresh Archive Listing" from the addon to refresh the list you edited.

11. How do you get Retroarch/Retroplayer to do XYZ?

Hold on there tiger. This addon is a game LAUNCHER. Not an emulator. I'm no where near an expert on all the in's and out's of Retroarch (or whatever you're favorite emulator is). I suggest taking a look here. Or, head on over to the libretro forum or the libretro wiki.

12. When I try to launch a game, it looks like Kodi tries to play it with the DVD player.

You didn't to follow the steps on how to setup the addon to work with an external Retroarch installation. FOR SHAME! See the setup instructions here.

12b. When I try to start the addon, it fails. The error log says something about "ImportError: No module named XXX"

The error you got is due to dependencies that did not install for some reason (which should auto install if you install IAGL by zip or by my repo, you likely copied the files manually so the dependencies weren't installed). To avoid this, install the addon using the repository as discussed on the install page.

To fix this, you can manually install the dependencies by searching for them. The dependancies are listed here.

13. This addon shows up as a video addon, and not a program addon.

Yes, thats by design. This addon will show up as both a game addon and video addon. Kodi skins tend to have more views available for video addons rather than program addons. It's in video addons by default to allow for the most viewtypes. If this effects your OCD, I suggest you just make a bookmark/favorite for the addon and set it up to appear wherever you like in the Kodi skin of your choice.

14. Game XYZ does not work, your addon is broken!

14a. Game XYZ starts, but has issues, your addon is broken!

Maybe. But probably not...

If the game launches, then IAGL is no longer "in the loop". The addon did its job. The game launched. Done.
After that, it's up to whatever is emulating the game. So if the game launches, but has some sort of issue, then I suggest you google search for the specific issue you are experiencing along with the emulator being used (the retroarch core, or Retroplayer addon, etc), look at your settings, etc.

14b. I pressed launch but nothing happened, your addon is broken!

Maybe. But probably not...

In a nutshell this is how IAGL works:

  1. Downloads the required files you requested from the archive
  2. Processes those files (if necessary) to get them ready to launch (unzip for example, some others have config files automatically generated).
  3. Executes a command line command to launch the game. This would in theory be the same exact command you would use to launch the game from the command line.

Most likely causes that game XYZ does not work are (in no particular order):

  • You did not setup your emulator exactly as required for the game to work
  • The settings for your emulator need to be tweaked for the game to work
  • The game is not supported / is not compatible yet with the emulator you tried
  • IAGL did not send the right launch command or did not provide (all) the required files
  • IAGL did not download the file, or all the files required, or they're no longer available, or... you're not connected to the internet (did you try this)

For troubleshooting purposes, I suggest the following:

  1. Review the launch commands for the archive you're having trouble with. You can do this by selecting the archive list in IAGL, then bringing up the context menu and selecting "View List Settings". Ensure the launch command looks correct for the emulator / core you're using. Note that the wizard is not 100% correct, and Retroarch / core functionality changes often so it could require the command be tweaked to work. See here on info on tweaking. Launch Commands

  2. Assuming the game downloads from IAGL correctly. Start Retroarch and launch the game directly from the emulator (i.e. start retroarch and try and launch the game file that IAGL downloaded). If that doesn't work, then the problem lies with your setup or the emulator (hint: It's probably a BIOS file issue).

  3. You can turn on debug logging in Kodi, attempt to launch your game, it will still fail, but then you can review the log and see what command is sent. Review the command, or even better, copy and paste the command into the command line for your computer and see what error you get.

If you believe you found a bug, let me know and I'll see if I can fix it. You must provide a debug log so I can follow what the issue is.

14c. I can launch games but there's no sound, your addon is broken!

You are probably using a Raspberry Pi. Am I right? Per the libreelec builds page (although the same issue and fix is applicable for Gamestarter build) All the emulators use ALSA by default. Some times there are more than one sound card or more than one output and the sound will go to the wrong place by default. In this case you should have a look at /storage/.config/asound.conf.sample. Use it as a template and save the edited one as /storage/.config/asound.conf. When done correctly the command "speaker-test" should output noise. If it doesn't you need to fix your asound.conf

14d. I try and download a game and I got an error!

Some archives on archive.org are only available after you login to the site. Enter your user EMAIL and password for archive.org in the addon settings. You can also check your login in addon settings.

If you did enter your email and password and it still gives you this message, it's entirely possible archive.org no longer provides the file(s). If this is the case, submit an issue with 1-2 examples of failed games, along with a debug log showing the failure.

15. I'm on Android and I can't change the download path for games

Android prevents apps from writing to external locations with (overly restrictive) permissions. You have two options:

  • If your system is rooted, you can update Kodi's permissions. See here.
  • You can write to the external location provided it follows the folder naming rules of Android.

For most Android devices, your directory can be named as follows on your external storage:

/[your_SDCard]/Android/data/org.xbmc.kodi/[folder_name]

example:

/SDCard2/Android/data/org.xbmc.kodi/NES
/SDCard2/Android/data/org.xbmc.kodi/SNES
/SDCard2/Android/data/org.xbmc.kodi/Genesis
etc.

For more advanced users, Kodi provides a method that is described here

For nVidia Shield, you can put data into a writeable folder on the external drive named NVIDIA_SHIELD. Additional info here.

15b. I'm on Android and my controller stops working when I launch Retroarch using IAGL

If you have no input from any of your controllers (buttons not working) when launching games from within Kodi using IAGL but you do when launching from Retroarch standalone then change the 'Poll Type Behavior' under the Retroarch 'Input' settings to 'Early'.

16. Can IAGL launch games hosted from Google Drive / Dropbox / My online host of choice?

Yes! The only requirement is the path to the game file(s) is fully resolvable (i.e the URL is known). Creation of a games list for files hosted on Google Drive or Dropbox, or even on your own local NAS (provided it can serve up http) will work. You can create you're own little internet archive at home if you wanted to.

Here's a few examples you can follow, using a public domain Game:

You'll see in the above examples, you have to point to the html link for the game file. Finding the html link for a Google Drive file can be found using the tool here For a google drive file, you also need to append a filename to your html link like this: &name=/GAMEFILENAME.nes

Use the example above for something to mimic.

Info on converting a direct link for Dropbox can be found here.

17. Bugs

The addon isn't perfect, but it's close! Here are the current known issues

18. DMCA

To the best of my knowledge the Internet Archive has an exception to the standard DMCA-related copyright rules found in the United States.

Reference this wikipedia entry, summarized below:

"The Internet Archive has created an archive of what it describes as 'vintage software', as a way to preserve them... the exemption is 'for the purpose of preservation or archival reproduction of published digital works by a library or archive.' ... the exemption was renewed in 2006, and in 2009 was indefinitely extended pending further rulemakings... In 2013, the Internet Archive began to provide abandonware video games browser-playable emulators such as MESS..."

Further documentation of the exemption can be found here, and here, and here.

This addon accesses archive.org data and web pages. Review the terms of use for archive.org here. Specifically archive.org states "Some of the content available through the Archive may be governed by local, national, and/or international laws and regulations, and your use of such content is solely at your own risk"

19. How can I help?

You can do one of these things:

  • The number one thing "the masses" have noted in various forums is that "IAGL is too hard to setup". I can understand this sentiment - IAGL (and emulator front ends in general) is a delicate balance of working easily and working for everybody. As you can imagine it's hard to provide a one size fits all solution with infinite tweak-able options for 50 different operating systems that all work a little different. That being said, this is totally an open source project - please submit your suggestions for updates to the setup wiki here.

  • Be creative and make a list of games to share with the community. Info on how to do that here.

  • I've made this addon for the fun of it, so personally not looking for any donations. BUT, I highly recommend a small donation to the internet archive to support their cause and their bandwidth.

Please donate here: https://archive.org/donate/