How to port a gog.com game for gogonlinux - Morgawr/gogonlinux GitHub Wiki

This page's aim is to provide an extensive guide to port gog.com games to the Gogonlinux project, following a step by step tutorial accessible to anyone, even non developers.

It is strongly suggested to anyone attempting to port games to have some prior knowledge on bash scripting and Unix (specifically Linux) utilities/commands in general as they are used extensively by the gogonlinux suite when installing and running games.

Before attempting to port games make sure you have access to the following tools which are required by gogonlinux:

• Innoextract
• Scummvm
• Dosbox
• Wine

Refer to the Getting Started page for more details on which versions are required and how to install them.

Obviously you will also need a working Linux environment with Bash shell and standard Unix utilities. Additional software and dependencies usage in the installation scripts should be avoided in order not to cause compatibility issues although there are some exceptions (for example Zenity, explained later).

Porting a game to run on gogonlinux can be either really simple or really complex depending on the game and how you approach this process so I'll work with you trying to make it as simple as possible, hoping not to hit any hard-to-overcome obstacles along the way.

The first and foremost thing you need to do is make sure the game actually runs. This is required for pretty much any game and is a no brainer. Do not submit requests of ports you have worked on that do not run. You are free to submit analysis of games and possible solutions on the gogonlinux forums so other developers and contributors can try solving the remaining issues however do not submit anything that doesn't run. It's just a waste of time for the maintainers of the project and does more harm than good.

Another really important thing when trying to port games is to be methodical. Approach the whole process documenting any step you perform so you know what you've done and how to re-create each and every step for the maintainers. We work on a big number of games and having to waste more time than required can be really frustrating, you can make our job easier and we'd be very grateful for this.

After you're done and think you have successfully ported a game, do it again. This is the best way to make sure other people can apply your scripts and get a working game. Start from scratch with a clean copy of the game and then patch it with your scripts and see how it works, if it works then chances are you successfully ported it... else you can go back and retry fixing errors along the way. Please do not send us anything that you haven't previously tried to install from scratch.

Once you have identified the game you wish to port from the gog.com library, download all its related files (usually just a setup.exe, occasionally bigger games are split with different .bin files) and make sure they are in a folder all together.

Now you will need to use innoextract, a tool used to extract files from innopackages which is the format used by gog setups. $ innoextract setup_mygame.exe

Even if you have multiple files downloaded run innoextract only on the .exe, every other file will be detected and extracted automatically.

After the extraction process has completed you should have two directories called app/ and tmp/

NOTE: Some dosbox games have also a directory called code:getdosboxfromini|path, you can ignore this at the moment but please keep it in mind for later.

Remove the tmp/ directory since it's useless and is just some extra stuff for the gog installer (not relevant to the game), change name to the app/ directory to the name of your game and cd into it

$ rm -rf tmp/

$ mv app/ mygame

$ cd mygame/

Since version 0.2.4 of the project it is now possible to force the download of unsupported games through the command line. This simply automates the download+extraction process without tainting the extracted data (no patching nor installation of launch scripts). You just need to download the game normally as you would through gog-installer for any supported game, just add the --force flag. $ gog-installer --force <game-id> Any game downloaded/extracted through this process will have to be uninstalled from the gogonlinux database like you would with an official game, so you will have to run $ gog-installer -u <game-id> once you are over with the porting process (or if you want to restart from scratch, maybe to test).

Now you should be in a directory which contains all the installed data for the gog game. This will be our root directory and where the porting process will start, head onto step 2.

All gogonlinux games have to be emulated in a way or another, at least until gog.com starts providing native Linux games, hence they will require a specific type of emulation depending on what we're trying to run.

There are three different emulators the gogonlinux project currently supports: scummvm, dosbox and wine. I won't go into details for each of them but the general rule of thumb is: If gog.com ships the game with scummvm or dosbox, then it's a scummvm/dosbox game. Else it uses wine.

If the game uses scummvm/dosbox chances are that you'll see a folder called DOSBOX or ScummVM lying around in the root directory, that should be an indicator enough to tell you what type of emulation it uses.

A lot of files shipped with gog games are unnecessary and not required to run the game on Linux so we'll have to remove them manually to make the root directory a more pleasant place to work in. Less clutter makes for a better development process and also the end-user/player won't have to be troubled by unnecessary files.

Identifying unnecessary files isn't easy. It depends heavily on which game we're porting and how much experience we have in porting gog games. This is a list of unnecessary files you may want to remove:

• gfw_high.ico
• "Graphic mode setup.exe" (yes, just one file)
• innosetup_license.txt
• goggame.dll
• gog.ico
• Support.ico
• GameuxInstallHelper.dll

Keep in mind that in the case of a dosbox/scummvm game we'll be going to use the native Linux clients and not the one provided by gog.com so you will have to remove the respective DOSBOX/ScummVM directory as well since not required.

Please keep track of the files you remove during this step as they will have to be removed in the end during the install script.

This is the crucial step, we have to get the game to run on Linux. This part is either very simple or very complex (if not impossible) depending on the game and type of emulation. Please refer to the correct section for your porting process, it depends heavily on the type of emulation you're working with.

Dosbox is fairly straightforward and most games will run easily out of the box without requiring any patching or config modification, although checking and testing is always a good idea as there are some exceptions.

Start by detecting the main .exe file to launch. There may be several different .EXE (yes, in caps lock usually, that's how it was done back then) programs so detecting the correct one might take some time.

Note: some games may use a .bat file to start.

As usual with dosbox, start the game with the command $ dosbox MYGAME.EXE and see if it works. If it does then you're in for a treat. If it doesn't run, however, you may need to investigate on the matter and see how gog launches the game (they usually have .conf files). Some games have been reported to require specific dosbox settings or some local dosbox partitions (like CDs or floppies) mounted. A good place to start would be the dosbox man page which outlines several different options you can try.

Be sure to note the required command to run the game, it's going to be needed later when writing the launcher script.

About config files: Several dosbox games on gog.com already come with their own .conf file used to launch them. This file contains all the settings that the gog guys thought would yield the best compatibility for the game. Usually one thing you may want to do is change the "fullscreen=true" line to "fullscreen=false" so the game doesn't take hold of your whole screen. Then consider launching the game with the -userconf -conf myfile.conf parameters. In the future gogonlinux will support running and editing these settings as default so it's best to use them right now instead of relying on the global dosbox configs and having to change later.

ScummVM is very easy to get running and with most games it will work out of the box without having to edit any config files.

First of all detect the scummvm settings file. It's usually a .ini file with all the settings and options required. This is the file that we will have to pass to the scummvm app using the -c flag.

With scummvm we don't need to provide a .exe file since the program automatically detects the game when given the game path, we can test this with:

$ scummvm -p "$(pwd)" -c "mygame.ini"

As you should already know, the pwd command outputs the current working directory (the directory we have cd into). Through the -p parameter we make sure scummvm uses that defined path instead of using a globally accessible one, it is useful when dealing with self-contained environments.

If the game is a scummvm supported game (which should be since gog.com uses it), then it shouldn't have any problem running and your port should be pretty much completed. However issues can arise and those should be all reported to the scummvm project, not to us.

This is the real problem when porting games and is the one that requires more experience and dedication. Wine is a huge project that affects a huge portion of your working environment so the porting project will probably be very messy and troublesome (especially for the inexperienced).

I'll try to explain everything the simplest I can get but don't read this if you aren't confident with your wine knowledge, it can do you more harm than good.

Make sure you are running the latest wine development version. I can not stress this point enough, if you're planning to work with wine you are going to need the latest version. Normal users may or may not have the latest and most up to date version but you, as a developer, should always work with that one. There will be version mismatch and compatibility issues but there's little we can do and if the users really want to run those games then they will have to obtain the latest version.

To get the most up to date version go to winehq, download the sources and compile it yourself. If you have a rolling release distro you can also obtain it through their package manager, it doesn't matter (on Ubuntu there's probably a ppa for wine too).

This said and done, let's start approaching this cumbersome porting process.

When working with wine you should have a good knowledge on how wineprefixes work, our objective is to have each game with its own wineprefix version so we can store all the settings and required configurations without polluting the global wineprefix.

Start by testing if the game works on your own global wineprefix, ideally you'd want to support the most commonly required options through winetricks (like d3dx9, fonts, dotnet, etc etc) so you fallback to the most globally compatible setup and then restrict the required dependencies until you hit just the bare minimum (so we don't install extra unnecessary stuff on the end-user's machine).

If you cannot get the game to work with your setup you should have to take a look at the winehq appdb page to read about the status of the application, possible fixes, patches, required winetricks setups etc etc. Wine is a various and broad project and each game requires its own finetuning and setup so there's not much I can tell you here, you will have to experience and test on your own until you come up with a working setup.

Since we provide the user the capability of running a virtual desktop we should be testing games both native fullscreen and through a virtual desktop. Be sure the game runs in both cases and if not keep that in mind and point it out when submitting the port to us so we can take notice of it.

After you have the game running on your global prefix it's time to start checking on your locally contained wineprefix and see what we need to install/setup to get it working.

Every wine gogonlinux game has its own wineprefix in the root folder(pwd). There are a few exceptions for games that don't seem to support a specific wineprefix but that isn't normal and shouldn't be your concern.

To make sure you have the right wineprefix, cd into the root directory of the game and start with $ WINEPREFIX="$(pwd)" wineboot. Always prepend WINEPREFIX="$(pwd)" before any wine command you run so you know you're operating in the right directory, same goes for winetricks too obviously.

Note: In case of episodic games or multi-game packages, run the wineprefix in the root folder and don't create a wineprefix for each sub-episode/game. This makes sure we have a single profile shared by each and we don't duplicate installed dependencies.

Apply all the winetricks patches and download the required overrides inside the local wineprefix and verify that the game runs (again, both virtual desktop and fullscreen). If you've done this and it works, then you successfully ported it.

Note: Running a virtual desktop as described here is different than running a virtual desktop setup through winecfg. Gogonlinux's virtual desktop uses the first approach so please use the former when running a virtual desktop and not the latter, this will help with compatibility.

Please consider contributing to the wine project as much as you can. Report bugs, applications, problems and solutions. The project is always in need of more contributors and just by sharing your solution to get a game to run on Linux with other people (through AppDB) you are doing the Open Source world a huge favor, people will be grateful to you.

The gogonlinux suite supports three types of bash scripts that will be run at three different stages.

• The install script is run after the application has downloaded and extracted the setup.exe files and removed the tmp/ and app/ directories, locating all the contents in the root directory.
• The launch script is run every time a user launches the game and is located in the root directory.
• The uninstall script is run after the game is deleted from the local game database and is used to clean up the filesystem for stray files.

Before proceeding, please download this template which will be used as a starting point for the rest of the script.

The install script is executed after the application has been extracted and has only one requirement: the first argument of the script will be the path where the game is installed. Knowing this, we'll cd to that directory and then perform any type of cleanup and setup operations required by the game.

Usually you want to start by removing all unnecessary files that we have marked in one of the earlier steps. Be sure to list all of them although missing a couple won't be vital as they shouldn't interfere with the game's playability.

Note: if the game is a dosbox game and you have previously identified a directory called code:getdosboxfromini|path, add the line rm -rf "code:getdosboxfromini|path" to your install script inside the root directory.

Now we need to perform modification of some default settings for dosbox/scummvm games. Usually you'll want the game to not start in fullscreen mode so run a small sed command to change the incriminating line.

If the game runs with wine you will want to launch wineboot (this is mandatory for any wine game as it will initialize the wineprefix) and additional winetricks scripts/registry edits required to tweak the game and make it run. Just follow what you did in the previous step and write it into the script.

Make sure everything is correct and you didn't forget any setup step.

Before proceeding, please download this which will be used as the starting point for the rest of the script.

The first few lines of the script are required to let the script find out about the directory the game is installed in. Every game runs with its root directory as pwd so we know all scripts and paths will be relative to that (there are some exceptions but don't worry with that).

Then, if the script requires additional input and options from the user at runtime, we can spawn a Zenity instance with the required questions and results. Grabbing those results we can then plan accordingly. Usually, this is used on games with multiple episodes or executables (like bundles) to ask the user which one they'd prefer to run.

If the game uses wine, uncomment the lines about utilizing a virtual desktop. It's a small script that detects the settings for a virtual desktop and enables/disables it accordingly.

As for the rest, just follow the steps you used when running the game by itself and apply them to the launcher script, planning accordingly to the emulation type for said game. It's pretty straightforward following the template.

Currently no game requires an uninstall script as their install directory is mostly centralized and separate from the rest of the system so there is no requirement to do cleanup of extra files. If you really need an uninstall script, write your own and submit it to us, we'll check it out and tell you if it works or not.

This is the final step, it's the verification process to make sure everything works properly and you managed to successfully port the game to the gogonlinux project. Note: Remember to chmod +x your scripts so you can actually execute them.

Starting from version 0.2.4 gogonlinux supports private repositories. This means that users can write their own repository (similar to the official one and install games through that. This is perfect both for normal users wanting to try extrenal repositories and for developers who want to test and port games.

In this case all you have to do is write a fake/dummy repository pointing to your install/launch/uninstall scripts and then pass it to the gogonlinux client to test if the installation process works well. If it does then chances are it will be ready for the official repo. If it doesn't then you will need to tweak and fix the porting issues. Please refer to this page for the repository protocol used by gogonlinux to know which format is recognized by the application.

Run the following steps and test if the scripts work or not:

$ mkdir mygame

$ cd mygame

$ innoextract /path/to/setup_mygame.exe

$ rm -rf tmp/ && mv app/* . && rmdir app

$ /path/to/install_mygame "$(pwd)"

$ cp /path/to/launch_mygame startgame.sh

$ ./startgame.sh

If everything works fine then you should have your game started and you successfully managed to port it. If there are problems during this process you will have to go back and fix them. Be sure to test with different setups and verify it works every time, the more tests you do the better we can guarantee the game will run on other people's computers.

Now that you have successfully ported your game, you will have to submit it to us so we can test, verify and add it to the gogonlinux list of available games.

To do so just send us an email at [email protected] with the following data:

• ID of the game - This is usually the title of the game with underscores instead of spaces. It's the string after the url "http://www.gog.com/gamecard/" in the game's page on gog.com.
• Title of the game - This is the title of the game, it's what is presented on the game's page on gog.com.
• Install script
• Launch script
• Private repository - The file you have used in step 6 to install and test the game (if you used a private repo of course)
• Additional notes - Anything you feel like telling us, how to get the game to run, how well it works, caveats, bugs, problems. Anything.

Please include a sensible title explaining what you have ported, prefix the email title with [PORT] so we know what it's about (and can easily filter it).

And that's it! You successfully ported the game to the gogonlinux project. We'll let you know if the port has been accepted and/or if there are problems so we can work together to fix them.

---

Thanks for reading all of this, I hope it was informative and helpful. In case of additional questions or corrections or anything, feel free to post on the gogonlinux forums and we'll be happy to help.