Guide
First Steps
Welcome Page
This is the welcome page where you can get started with omikuji. Yes it’s very tiny. From here you can click the ‘install runner’ button to install a runner from the default list.
If your system lacks umu, as you can see, you can choose to let it install by keeping the toggle on. It’ll install a built-in umu-run. If it happens that you have umu-run already installed system-wide, it’ll hide the option.
Welcome’s Component Installer
This is the welcome component installer where you can install a runner from the default list by clicking install (optionally you can choose which version of each release with the filter, if more than one option is available (_v3, x86_64, etc.)).
The ‘Latest’ option will install the latest release and it’ll update automatically the next time you start omikuji, if a new release is available.
Logging into Epic Games / GOG / Amazon Games
First, select one of the three stores in the left navbar.
Then, click the ‘Open Login Page’ text. It’ll redirect you to the Epic Games, GOG or Amazon Games login page. From there, login with your account, it’ll open one of the three pages (Epic Games, GOG and Amazon Games respectively).
For Epic Games, you need to copy the authorizationCode key.
For GOG, you need to copy the authorization code from the link itself after the code= text (mind it’s very long. make sure to copy it all).
For Amazon Games, the login lands you on a normal Amazon page. Copy the full link from the address bar and paste that, omikuji pulls the code out of it. Copying just the openid.oa2.authorization_code= value works too.
Paste the code into the input field and click ‘Login’.
Adding/Installing a Game
Omikuji has a bunch of ways to install games.
Stores
Steam
Steam doesn’t install anything from the launcher, you need to install games from Steam itself. However, you can import them in your library by just clicking the + button on the bottom left of the card. Importing Steam games gives them the steam runner type, that means it delegates the game launching to the Steam client.
Epic Games / GOG / Amazon Games
Omikuji uses Legendary to manage your Epic Games library, gogdl for GOG and nile for Amazon Games. You can scroll the page to see all the games you can install. By clicking the +, it opens an install dialog.
The Installation path field is where the game will be installed.
The Prefix path field is the prefix you want the game to use when installed and added to the library.
Runner dropdown is where you can select the runner to use for the game. (Along with the prefix path, these two will just seed the game settings after the download is finished and the entry in library gets created, you can of course change them later in the game settings)
DLC checkboxes are where you can select the DLCs to install with the game. You can select multiple DLCs at once or select none at all. You can also install DLCs separately after the game is installed, just re-open the game’s store card and checks the DLCs you want and press the Install DLC button.
All this applies to GOG installations too, they’re the same.
Amazon Games works the same way minus the DLC checkboxes, Amazon ships DLC as part of the base game so there’s nothing to pick.
One thing specific to Amazon Games: nile can’t resume a partially downloaded file. Pausing a download throws away whatever file it was writing at the time, which on a game built around one large archive can be several GB. Finished files are kept and get skipped when you resume. The downloads page shows this on the download item, and pausing an Amazon download asks for confirmation with the amount at risk.
Gacha
Gacha games are similar to Epic Games / GOG installations. However, some of them come with packs to pick: HoYo games have Voice Packs (check as many as you want, the first one is preselected), and Wuthering Waves has Texture Packs (SD, HD or UHD, pick one, HD is preselected). The install size shown includes the packs you picked. Packs can also be added or removed later from the game’s Gacha settings tab. Also, if the game supports, you’re able to change the version (Global, CN, JP, etc.)
Some gacha may come with additional things like, for example, Genshin Impact has a toggle to install the Fps Unlocker. If checked, it will install the latter alongside the game and will apply, in the game’s settings, the Companion field filled with the path to the unlocker executable. Other toggles only add launch arguments or environment variables, like DirectX 12 for Zenless Zone Zero, and can be changed later from the game’s Gacha settings tab. Some toggles, like the HoYo Timeout fix, only show up there and not in the install dialog.
Or additionally, some gacha may have a ‘suggested’ runner, which, if selected, will be installed on the spot and applied to that game (for example, hsr, that needs a specific Dawn Winery Proton to run). You still are able to select any other runner from the list and ignore the suggested one.
Also some gacha games may have a ‘temp path’ separated from the game’s install path. The temp path is used for storing temporary files during the game’s installation or update process. You can point the two in two different locations entirely.
Manually
Games that don’t come from a store get added by hand with the + button in the top right (and then Add Game in the small popup), which opens the New Game dialog.
In the Game Info tab, a Name is the only thing actually required, everything else can be filled later. The Runner dropdown is the important one:
- Wine for Windows games (.exe)
- Native for Linux ones (binaries or .AppImage)
- Steam to delegate the launch to the Steam client (requires the game to be installed in Steam)
- Flatpak for flatpak apps.
In the Runner tab you’ll want the Path to the executable (for Steam and Flatpak you get an Application ID field instead), a Version (the wine or proton build it runs on, install one from Settings > Components if the list is empty or just drop one manually in the runners dir) and optionally a Prefix. Leave the prefix empty and omikuji creates a fresh one for that game.
Create adds it to the library, Create & Play adds it and launches it right away.
This is the short version. A good amount of fields in both tabs, plus the translation layers, environment variables and everything else, is covered in Game Settings below.
Import
If you want to add an Epic Games, GOG, Amazon Games or Gacha game, you should NOT add them manually! Instead, go to the store the game is from and click the game card’s + to open the dialog of the game you want to import.
Epic Games, GOG & Amazon Games
For all three, there are two situations:
- The game is installed AND there’s an entry in Legendary/gogdl/nile .json files. This will lock the path since it already knows where the game to import is. Pressing import will add the game to the library with that path.
- The game is installed but there’s no entry in Legendary/gogdl/nile .json files. This will let you choose the path manually, since we want to import, you have to specify the path where the game is currently installed. Pressing import will add the game to the library with that path.
For Repairs, the game has to be installed and in the library. You’ll find the game in the store, open the install dialog, it should resolve the installed path automatically (since it needs to be registered in the Legendary/gogdl/nile .json files). Hit repair and it’ll repair the game. Careful! Legendary will repair as the term intends! GOG will reinstall the game. nile re-checks every file and re-downloads the ones that don’t match.
Gacha
For Gacha games the pattern is the same, with the difference that you’ll always have to specify the path manually. Also, as the note chip says when it successfully finds the game in the path specified, make sure to select the proper version of the game (e.g. Global, CN, etc.) so the game will be registered properly. This is important for gacha updates.
Also, for most games it’ll detect the installed game version automatically.
For games with packs, the packs already on disk are detected: voice packs found on disk are locked in the list, and for Wuthering Waves an installed texture pack is preselected. Picking packs that aren’t on disk queues them for download right after the import.
Regarding repairs, HoYo and Kuro games support them.
Downloads
You can check your own downloads in the Downloads tab in the left navbar.
When starting a download from any store, if nothing is already in progress, the download will start automatically. If there is already a download in progress, the download will be queued and will start once the current download is finished or paused.
From the page you can see the net speed, the disk usage, and the progress of the download.
Game Settings
Per-game settings open from the library: right-click a game and click Configure, or use the gear button on the bottom floating bar. Changes are staged until you hit Save or Save & Play.
Runner type
On the Game Info tab, the runner type decides how the game launches:
- Wine: run a Windows game through wine or proton. The default for most things.
- Steam: hand off to Steam, for imported Steam games.
- Native: run a Linux binary or .AppImage directly.
- Flatpak: launch an installed flatpak app.
The rest of Game Info (name, artwork, color) is optional and self-explanatory.
Runner (Wine)
Wine/proton config. Only shown for Wine games. (we’ll see the settings per header)
Executable
- Path: the game’s .exe.
- Working Directory: where the process starts. Empty uses the exe’s folder.
- Arguments: passed to the game, e.g. --skip-intro, -use-d3d12.
- Command Prefix: prepended to the whole launch command, for a custom wrapper.
Wine
- Version: which wine/proton build to use.
- Prefix: the wine prefix. Empty auto-creates a fresh one per game (named <slug>-<id>), the usual setup.
- Architecture: 64- or 32-bit prefix.
Translation Layers
- DXVK: Direct3D 9/10/11 to Vulkan.
- VKD3D: Direct3D 12 to Vulkan. This is VKD3D-Proton, the fork Proton ships, not Wine’s own vkd3d.
- DXVK-NVAPI: exposes NVIDIA features (DLSS, Reflex).
Toggling a layer on shows a version dropdown under it. Built-in leaves the dlls alone and uses what is already there. Picking a version, instead, makes omikuji install that version.
Off sets the layer’s dlls to Wine’s builtin ones (=b), so the layer’s own dlls never load even if they are in the prefix. The game gets wined3d instead of DXVK and Wine’s own d3d12 (built on Wine’s vkd3d) instead of VKD3D-Proton. DXVK-NVAPI off leaves no nvapi at all, since Wine has no builtin nvapi. On Proton the same overrides are held in place through the runner, explained further down.
VKD3D-Proton uses DXVK’s DXGI, so VKD3D on with DXVK off does not work.
take these infos a bit careful, I’m pretty confident of all of this but I might be a stupid
Built-in differs per runner. On Wine it is whatever dlls are already in the prefix. If the prefix has none for that layer, Built-in is greyed out if a toggle is on, because Wine would fall back to its own Direct3D without saying so. For a prefix that does not exist yet and you’re adding a new game, the note under the dropdown says whether the layer gets installed when the prefix is created at launch, which follows that layer’s auto-install on prefix setting in Settings -> Components. On Proton it is the layer bundled in the runner’s files, which Proton deploys into the prefix at launch.
Installing a version works the same on both. omikuji copies the version’s dlls into the prefix at launch, and a layer on Built-in gets the runner’s bundled dlls copied instead, so a prefix shared by two games always holds what the game being launched asked for. The runner’s own files are never changed.
On Proton neither turning a layer off nor picking a version can be done with an environment variable alone. Proton writes its own dll overrides after every hook it exposes, and copies its bundled dlls over the prefix at launch. omikuji writes a user_settings.py into the runner folder, a file Proton imports when present, which reads two environment variables set at launch: one holds the overrides of the layers turned off, the other stops Proton from copying the dlls of the layers with a picked version. Each layer is handled on its own, so a picked DXVK version does not change what happens to VKD3D-Proton. It does nothing when those variables are absent, so the runner behaves normally for Steam and for anything else launching it. I will gladly say Proton, fuck you.
If a runner already has its own user_settings.py, omikuji leaves it alone and these toggles and versions will not apply. The Runner tab says so, and the same warning shows for a Proton build without the hook.
Misc
- Display: DPI Scaling with a DPI slider.
- Drivers: the wine Audio Driver (Default, PulseAudio, or ALSA).
- Graphics Driver: X11/Wayland picker.
- DLL Overrides: Key-value pairs of DLLs to override with their path.
Runner (Steam)
- Application ID: The Steam application ID of the game.
- Arguments: arguments to pass to the game.
Runner (Native)
- Executable: binary or .AppImage of the game path.
- Working Directory: the parent directory of the game.
- Arguments: arguments to pass to the game.
- Command Prefix: prepended to the whole launch command, for a custom wrapper.
Runner (Flatpak)
- Application ID: the flatpak application ID of the app.
- Arguments: arguments to pass to the game.
System
Performance: GameMode (Feral’s gamemoderun) and a CPU core limit.
Display: MangoHUD overlay and the GPU to run on. The GPU list comes from your installed Vulkan drivers, handy on multi-GPU setups to pin a game to the dGPU or iGPU.
Audio: Reduce Pulse Latency.
Power: Prevent Sleep keeps the screen awake while the game runs.
Discord Rich Presence: enable Discord Rich Presence for the game.
Gamescope: runs the game inside Valve’s gamescope compositor. Enabling it exposes output and game resolution, an FPS and Refresh Rate cap, fullscreen or borderless, integer scaling, and an upscaling filter (FSR, NIS, nearest, linear) and HDR.
Environment: env vars to use when launching a game.
Sets: Stored env vars that you can:
- Sync (they will be used along the current game’s ones. Synced ones are not added in the game settings, so, changing a synced set will apply to all games)
- Add: (adding an env set will apply the contained vars to the game settings).
Scripts:
- Pre-Launch: Script to run before launching the game (waits for the script to finish before launching the game).
- Post-Exit: Script to run once the game exits (waits for the game to close before running).
- Companion: Script, binary or Wine .exe to run with the game. Windows files (.exe, .bat, .cmd, .msi, .com) run inside the game’s prefix with the game’s runner, if the game isn’t a Wine type, the companion will just make a default prefix for itself.
When you fill the path field, it’ll show you three more options below it:
Arguments: arguments to pass to the companion. Arguments are passed as they are, so shell variables like $HOME are not expanded here (they still work inside the script itself ofc). You can also use template literals.
When: when to run the companion.
- After the game: launches the game, then the companion.
- Before the game: launches the companion, then the game.
- Instead of the game: omikuji launches only the companion with its own arguments and starting the game is up to the companion. Nothing is implictly passed to it so anything it needs goes in Arguments, for example --game ${game_exe} --dir ${game_dir}. The game’s own launch arguments are not passed either, add ${game_args} to include them. For Wine games a Windows companion runs as wine <companion> <arguments> with the game’s runner, prefix and environment variables. A script or a Linux binary runs directly with the game’s environment variables. Not available for Steam games, since Steam starts them on its own and it’s whatever Steam wants to be as usual.
Delay: delay in seconds for the wait between the two (game and companion). For example, if When is After the game and you set delay to 10, the game will launch first and then wait 10 seconds before running the companion.
Epic
Only appears for Epic games.
- EOS Overlay: installs and enables the Epic Online Services overlay for the game (if it’s already installed you still need to enable it here, but it won’t download again).
- Auto Sync: Auto-sync pulls saves before launch and pushes them after exit. Save Path Override covers the case where the path isn’t detected automatically. Note that it won’t find the path if the game was never run first.
- DLC: List of the installed DLCs for the game. Legendary allows you to uninstall them, just hover the dlc you want to remove and click the x on the right.
GOG
Only appears for GOG games.
- DLC: List of the installed DLCs for the game. However, unlike Legendary, gogdl DLCs are not uninstallable.
But! If the page is empty, there’s a cute dino!
Gacha
Only appears for gacha games that have packs or launch toggles.
- Launch: toggles and choices that come from the game’s manifest. They don’t store anything on their own: each one adds or removes launch arguments and environment variables on the game, the same ones shown in the System / Runner tabs. A toggle checks whether its own arguments are already set in the game’s settings (launch args or environment variables). If they are, it reads as on, and turning it off removes those same arguments.
- Active pack (Wuthering Waves): which texture pack the game loads, through its -krqlv launch argument. Only installed packs are listed. None removes the argument, and the game won’t start without one as far as I know.
- Timeout fix (HoYo games): sets WINE_TIMEOUT_FIX=1 and UMU_USE_STEAM=1. Try enabling it if the game crashes on boot.
- DirectX 12 (Zenless Zone Zero): adds the -use-d3d12 launch argument.
- Voice Packs / Texture Packs: Installed lists the packs on disk with the space they take, Available lists the rest with their download size. Check the ones you want and hit Install selected to queue them in the downloads page. The game has to be on its latest version to add a pack. To remove one, hover it and click the x on the right. Removing the active texture pack (wuwa) asks for confirmation and switches the game to another installed pack first (the default one, HD, if it’s there). Removing a pack happens right away and doesn’t wait for Save, so be careful with that.
App Settings
You can configure the app settings in the Settings tab in the left navbar.
Here’s a little explanation of the settings tabs.
- App Settings: General settings for the app. Mainly behavior. Such as tray toggle, Legendary / GOG threads, Bandwidth limits, update checks, and more.
- Interface: This one for whatever is mainly the visual interface of the app. Language, zoom, card settings, icons, highlight logs (and rules), stores and library tabs toggle/drag.
- Defaults: Defaults for games. These will seed the games you’ll create in the library. It applies automatically for installed games, while, if you add them manually, they’ll seed the fields automatically but you can still change them before creating the entry of the game. You can also use the top right button, apply to existing, to apply the defaults to all the games in the library (it has various checkboxes to decide which categories of options to apply to the games in the library).
- Presets: Environment sets and DLL overrides sets for games. Sets are groups of key value pairs that you can copy in a game setting OR sync with the game’s settings (in the game’s settings). Syncing means that it does not copy the pairs in the game settings, but will apply them on top of the game’s ones at launch. So, if you add lets say, a ‘Raytracing’ set and sync it with a game, if you in future change the pairs set, the game will have the new pairs applied without manually editing the game’s settings. It also has Template Literals that allow you to use variables in some fields. For example, ${prefixes_path} will resolve the settings.toml paths.prefixes_dir value. Useful if you want to back up your settings, change user, and all games will resolve with the new prefixes path without any manual intervention per-game. You can also make custom ones.
Template Literals allow you do stuff like this. So that you can use variables in some fields, and as shown in the example I can just use this as a global variable that seeds any game I make, and it will resolve the game’s slug for the file name. I’ll just create that file with the parameters and it’s resolved without me having to do anything.
VKSUMI_CONFIG_FILE=${home}/.config/vksumi/custom/${game_slug}.conf
- Components: Here you can manage your layers (dxvk, vkd3d), runners (Wine-Spritz, Proton-GE, Proton-Cachyos, etc.) and runtime (umu-run, legendary, gogdl, nile, etc.) components. You can add sources for layers and runners from the Add Source button. Manage the already existing ones from the Manage button on each item (changing values, installing from Git releases, etc.). Runtime has a ‘Check for Updates’ button that checks if there’s an update available for any of the runtime components. Also you can reinstall them or delete them with the x button on the right. The Add Source dialog is explained in Adding a component source below.
- Ofuda: Essentially a prefix manager. Here it shows all your prefixes (in omikuji’s prefixes_path and any prefix used by a game in the library). You can check their sizes, how many games use each prefix (orphan if no game uses it anymore). You can also manage them with the Manage button. It will open a dialog with some information about the prefix and some actions, such as delete prefix and basic winetools commands (winecfg, winetricks, run wine command, kill wineserver, etc.). It will also tell you precisely which games use the prefix. There’s also a new prefix button on the top right of the page. It’ll open a dialog to create a new prefix with a Name field, Runner and Set dropdowns. The Set is essentially Game or Application (they just install a bunch of stuff in the prefix)
- Theme: Here you can change the theme of the application. There’s a follow system toggle for colors, if enabled it will use KDEPlasmaPlatformTheme6.so to follow the system theme. If off, you can change the Window background, content surface, accent, accent text, text, error, success, warning colors. Also a Font section, same follow system toggle, a font family picker (needs restart) and font sizes dialog that has display, headline, title, subtitle, body, label, caption, and micro spinboxes (also a reset all button). At the bottom there’s a Corner radius section that lets you manage various rounding spinboxes.
- About: Information about the application, including version, license and various links. Also your system information that you can copy paste for opening an issue.
Adding a component source
The Add Source button in Components lets you point omikuji at any repo that publishes runners or layers as release archives.
Name and Releases URL are the only required fields. Description is optional and Kind tells omikuji what the thing actually is (Proton or Wine for runners, DXVK, VKD3D, DXVK-NVAPI or Other for layers).
Releases URL takes a plain repo link, like https://github.com/owner/repo. You don’t need to hunt down the API endpoint yourself, links get converted to their releases API automatically. When the link you typed differs from what omikuji will actually call, the converted URL shows up in small monospace right under the field, so you can check it resolved to what you expected. You can also directly enter the releases API URL if you know it.
Latest build priority only shows up for runners, and it’s what makes the -Latest slot pick the right file. Some projects ship several builds per release (_v3, _x86_64_v3, aarch64, and so on) and you probably want a specific one every time. Write the tokens space separated, and the first one that matches wins, so anything further right is a lower priority fallback. If none of them match, omikuji falls back to its normal pick instead of giving up.
Skip releases with no match toggle appears once you’ve written a priority, and it changes what happens when the newest release has nothing matching your tokens. Off, -Latest takes that latest release anyway with the normal pick and follows the priority list. On, it skips an entire release if no match is found. Useful when a project occasionally publishes a release that doesn’t include your build flavour and you’d rather stay on an older one than get the wrong file and/or undesired version.
Move / Symlink to Steam compatibilitytools.d
If you want, you can move an installed runner that is in the runners dir to the compatibilitytools.d directory to make it available to Steam (and omikuji), you can just click the Steam button in the runner manager, it’ll open a dialog with the found Steam paths. If there’s only one path it’ll just move it there, if there are multiple paths (and you select more than one, since you could just select one), it’ll copy the runner in each selected path.
It changes a bit for the -Latest type of runners. In that case, it won’t copy nor move, it’ll symlink the folder to the compatibilitytools.d directory of each selected path. Why? Primarily because this way -Latest runners won’t be duplicated in the runner selection dropdowns, and then because we have to manage the update of the runner on new releases. Also, only when we symlink, omikuji will overwrite the compatibilitytool.vdf file in the runner’s folder to a generic <runnername>-Latest, with this when updating the runner, Steam won’t deselect it for games that use it. (yes, Steam reads that file, if the display or internal name of the runner changes, Steam will deselect it from the games you’re using it on, this prevents that.). Also, if you re-open the dialog, and there’s a symlink already, you will be able to uncheck the path and remove the symlink (once you apply the edits ofc).
Library Overview
Just some things about the main library. On the left there’s the navbar with the various categories for games and below them the stores, and at the bottom of the navbar we have the Downloads and Settings tabs (settings opens a dialog, downloads is a page). At center there’s the main library view. When you click a game card, it’ll outline it with an accent color and will show the bottom floating bar. In order, the floating bar has: Game title, Playtime, Last Played, Runner of the game on the left, then on the far right, still in order: Wine button (opens a context menu with Configure (winecfg), winetricks, Registry (regedit), Command Prompt (cmd), File Explorer (explorer), Run EXE in prefix..., Run wine command..., Kill wineserver). Running one of these will execute the corresponding action inside the selected game’s prefix (also, they’re 1:1 to the Ofuda buttons. Run wine command simply opens a dialog with a field where you can execute any wine command (winetricks is slow as balls to scroll through)). Then a gear button that opens the selected game settings, and a play button (has various states. Play, Stop, Starting.)
At the top of the library view there’s a search bar. On the far right on the same row (top right edge of the window) there are three buttons. In order: Console Mode (opens console mode), Quick settings (opens quick settings popup for the library), + (opens a popup with Add Game and Install Script entries).
Also, if in the settings (or quick settings) you enable the custom order for the cards sorting, you can hold with your left click a card for ~2 seconds and then drag it to a new position.
Right clicking on a game card will open a context menu. Its entries are:
- Play: starts the game.
- Show Logs: opens the game logs in a separate window.
- Configure: opens the game settings dialog.
- Categories: opens the game categories dialog.
- Browse Files: opens the game files in the file manager.
- Add to favorites / Remove from favorites: adds/removes the game from the favorites list.
- Hide/Unhide: hides/unhides the game from the library.
- Shortcuts: opens the game shortcuts subdialog. Create desktop shortcut, Create application menu shortcut, Create Steam shortcut. If they already exist, it’ll be Remove.
- Duplicate: duplicates the game entry.
- Remove: removes the game entry. Hold shift and it becomes Remove + prefix, it will open a dialog to confirm. It will remove the game entry from the library and delete the game prefix.
HoYo & Kuro Games
- Repair: repairs the game installation.
Epic Games / GOG / Amazon Games
- Check for updates: checks for updates for the game and queues them in the downloads page if present.
- Uninstall: removes the game installation (both from the library and the files on disk, also clears the Legendary/gogdl/nile .json files).
Quick Settings
- Card size: slider for the card size.
- Card spacing: slider for the card spacing.
- Sort by: dropdown for sorting the cards. Custom allows to hold a card with the left-click and drag it to reorder. Date added, Name A-Z, Name Z-A
- Card style: dropdown for the card style. Normal, Fit, Frameless, Vignette (default), Poster.
- Show hidden games: toggle for showing hidden games.
Community Scripts
Community scripts are essentially a DSL, made with .toml files and hosted in the scripts repository. They allow a user to run them for installing launchers, editing prefixes and such.
To install one, click the + button and select Install Script in the tiny popup. The dialog will normally just show the locally installed scripts in the scripts directory. To query online ones, just type something in the search bar. They’ll get listed. A script item has: an icon, a name, a small download icon beside it if it’s not installed, below them a short description and on the far right the author name on top of the last updated date.
Clicking a script pulls it locally and opens a new dialog. The fields in it are all declared in the script’s .toml file. The only thing that is always present is the show source button that expands a code block with the script’s source code. For more information, see the scripts documentation.
Keyboard and Controller
The whole app can be used without a mouse (hi steam deck user). Pressing an arrow key, Tab or any controller button switches to keyboard mode: the mouse cursor hides and the focused element gets an outline. Moving or clicking the mouse switches back. Enter and Space alone don’t switch modes (that’d be dumb wouldn’t it.).
Keyboard
- Arrow keys: move the focus to the nearest element in that direction.
- Tab / Shift+Tab: jump to the next / previous section. In the main window the sections are the sidebar, the top bar, the page content and the game bar at the bottom. In dialogs they’re the dialog content and its buttons.
- Enter / Space: press the focused button, toggle the focused switch or open the focused dropdown. On a library card it plays the game, or stops it if it’s running. On a store card it opens the install dialog, etc. Actions, whatever you want to call them.
- Esc: closes the open dialog or popup. In the library it deselects the game.
- Ctrl+Tab / Ctrl+Shift+Tab: next / previous sidebar entry (library tabs, stores, downloads, settings, game settings, etc.).
- Left / Right on a slider, number field or segmented control: changes its value.
- Dropdowns: Up / Down moves the selection on the next / previous item, Enter picks, Esc closes without changing anything.
- Right-click menus: Up / Down move, Enter picks, Right opens a submenu, Left goes back to the parent menu.
- E: opens the settings of the selected game.
- Q: opens the wine tools menu of the selected game if available.
- F or the Menu key: opens the right-click menu of the selected game.
- Ctrl+Plus / Ctrl+Minus / Ctrl+0: UI scale up / down / reset. Ctrl+ Arrow Up and Ctrl+Arrow Down too.
E, Q and F only work in the library with a game selected.
Controller
Buttons are named after the Xbox layout, the position is the same on other controllers of course.
- D-pad / Left stick: same as the arrow keys.
- A (bottom button): same as Enter.
- B (right button): same as Esc.
- RB / LB: same as Ctrl+Tab / Ctrl+Shift+Tab.
- RT / LT: same as Tab / Shift+Tab.
- Start: same as E, opens the selected game’s settings.
- Y (top button): same as F, opens the selected game’s right-click menu.
- X (left button): same as Q, opens the selected game’s wine tools menu.
Q&A
Where does omikuji install its own stuff, creates prefixes and store stuff? and can I change it?
What does omikuji manage on disk?
Everything omikuji creates or edits, grouped by where it lives. Paths under ~/.local/share/omikuji are the defaults and follow whatever you set in [paths].
Omikuji’s own folders
- ~/.local/share/omikuji/settings.toml: always at this path, since it’s the file that says where every other folder is.
- library/: one .toml per game.
- components/runners, components/layers: runners and DXVK / VKD3D-Proton / dxvk-nvapi builds.
- components/tools: companion tools that run alongside a game, like the ones a gacha manifest suggests.
- prefixes/: wine prefixes created by omikuji.
- gachas/: gacha manifests fetched from the registry and versions storing.
- scripts/: installed community scripts.
- runtime/: the runtime components (umu, hpatchz, legendary, gogdl, nile, the dummy EpicGamesLauncher.exe, etc.) and store state like gogdl and nile’s config, auth, installed games, etc.
- cache/: stores’ libraries, cover art, and cache/downloads/queue.json (downloads page entries).
- cache/logs/: omikuji’s own log for the last 3 sessions (omikuji_<date>_<time>.log, the newest one is the current session), and game logs when saving them to disk is enabled. Game logs are never deleted automatically.
Runner folders
- .omikuji.json: written inside every runner omikuji installs. It holds the source and release tag the runner came from.
- <Source>-Latest (e.g. GE-Proton-Latest): a normal runner folder with a fixed name. When a newer release comes out, its content is replaced and the name stays the same, so games using it never need to be edited.
- user_settings.py: written into a Proton runner the first time a game on it turns a translation layer off (DXVK, VKD3D-Proton, etc.) or picks a version for one. Proton imports this file on its own, and omikuji uses it to stop Proton from putting back the DLL overrides you disabled, or from copying its own DLLs over the version you picked. It does nothing unless the game was launched by omikuji with a layer turned off or a version picked, so the same runner used by Steam or other launchers behaves as if nothing was touched. If a runner already has a user_settings.py that isn’t omikuji’s, it is left alone and the layer toggles and versions won’t apply on that runner (also noted in the UI with a warning).
- .omikuji-dll-override.json and *.omikuji-bak: left by older omikuji versions, which swapped a runner’s bundled DLLs in files/lib/wine/ for the picked version. The next launch of a game on that runner puts the original files back and deletes both.
Wine prefixes
- drive_c/windows/system32 and syswow64: translation layer DLLs are copied here at launch. On wine runners these are the DXVK / VKD3D-Proton / dxvk-nvapi versions the game has enabled.
- Epic Games’ games: an Epic launcher registry key is added to the prefix, and drive_c/windows/command/EpicGamesLauncher.exe is copied in, because some games refuse to start without them.
Steam
- compatibilitytools.d/<runner>: a symlink (or the moved runner itself if not a -Latest type) when a runner is exposed to Steam from the Components settings. For symlinked runners (-Latest types), the tool name inside the runner’s compatibilitytool.vdf is rewritten to the folder name, so a -Latest runner shows up under the same name and Steam doesn’t deselect it when the runner is updated.
- userdata/<id>/config/shortcuts.vdf: the entry added by “Add to Steam”.
- userdata/<id>/config/grid/: the game’s art for that shortcut (<appid>.jpg, <appid>_hero.jpg, <appid>p.jpg, <appid>_icon.png).
Desktop & Others
- ~/.local/share/applications/omikuji.<slug>-<id>.desktop or ~/Desktop/omikuji.<slug>-<id>.desktop: desktop shortcuts, running omikuji run <slug>_<id> --notify-gui.
- ~/.local/share/icons/hicolor/256x256/apps/steam_icon_<appid>.png: a symlink to the game’s icon, (for anything like docks, shell previews, etc.).
Game install folders (gachas)
These only exist while an install or update is in progress, paused, or failed. They are removed when it finishes or is cancelled.
- .omikuji-dl-<game>: downloaded archive parts of an install. Created next to the install path, or inside the temp path if one is set.
- .omikuji-update-<game>: the same for updates.
- .omikuji-patch: a staging folder inside the install path while a patch is being applied.
- *.parts and *.omikuji-parts: small journals next to a partially downloaded file, recording which pieces are already done so a paused download resumes where it stopped.
My store page is empty, or it says I’m not logged in
See Logging into Epic Games / GOG / Amazon Games.
Why can’t I install Steam games from omikuji?
See Steam.
How do I add a game that doesn’t come from a store?
See Manually.
Can I install a DLC (Epic Games / GOG) for a game already installed?
See Installing DLC (Epic Games / GOG).
How do I run a random .exe inside a game’s prefix?
See Library Overview.
What’s the difference between copying and syncing an env set?
See App Settings.
How do I make a runner available to Steam?
See Move / Symlink to Steam compatibilitytools.d.
What are community scripts and how do I install one?
See Community Scripts.
How do I point omikuji at my own scripts registry?
See Configuration > [scripts].
How do I change the card size, sorting, or hide games?
See Quick Settings.
How do I uninstall a Epic Games / GOG / Amazon Games game?
Can omikuji use wine and proton builds already installed on my system?
Yes, they’re picked up automatically, no configuration needed. The runner dropdown lists omikuji’s own runners, every Proton in Steam’s various compatibilitytools.d directories and your system wine.
How do I update a game?
Several ways:
- Epic Games / GOG: Right click on the game in the library and select “Check for updates”. Or you can enable the toggles that check for updates on game launch.
- Amazon Games: Right click on the game in the library and select “Check for updates”. There’s no on-launch toggle for Amazon Games.
- Gacha: Gachas are always checked on launch.
All of them share the Settings -> App -> Check for updates on app launch toggle. If on, it’ll check for updates for every store and queues them in the downloads page if there are any.
Do I need umu?
Only for Proton. The app doesn’t implicitly install umu for you. You have a toggle in the welcome page or you can install it Settings -> Components -> Runtime -> Install on umu’s button. It will ask you if you want to install umu in other occasions such as when you launch a game with proton but umu is not installed. Also if you have umu installed system-wide, omikuji will use that.
A game ran once and now my DLL overrides (layers) are still in place
The runner itself is never changed, the picked version lives in the game’s prefix. On Proton, set the layer back to Built-in (or turn its toggle off) and run the game again, and omikuji copies the runner’s own dlls back into the prefix. On Wine the dlls stay in the prefix, and turning the toggle off makes the game ignore them.
Where are the logs?
For games, logs can be seen by right clicking the game card and selecting Show logs. It will open a new window with the logs when you run the game. Also comes with a search (Ctrl+F), clear, Copy all and Save buttons. Or you can enable the automatic save on disk in Settings -> App -> Save game logs to disk.
Can I install the same game twice?
For Epic Games, GOG and Amazon Games, no. But you can install as many copies as you want of a gacha game.
Can I use omikuji for regular apps instead of games?
Yes. Add the app the same way as a game and assign it a custom category. There is no separate “Apps” section, so it will also appear under All Games.