01
Getting started
Requirements
- Windows 10 or 11, 64-bit.
- Linux, 64-bit, in a regular X11 or Wayland desktop session. Running inside gamescope (SteamOS Game Mode and similar) is not supported. The Linux build is a preview: it is built but not yet tested on real hardware.
- A controller is optional. Any controller your system recognizes works for navigation; Xbox, PlayStation and Switch Pro button names are shown when the controller type can be detected.
Installing
Download the latest release from the releases page. No account is required.
- Windows: run the installer (
…-setup.exe) for a Start menu entry and an uninstaller, with no administrator rights needed; or run the portable.exefrom anywhere, or unpack the.zip. Both are the same program and update themselves. - Linux: make the AppImage executable (
chmod +x) and run it, or unpack the.tar.gz, which includes a desktop entry and icon.
Starting and quitting
Moonglass opens full screen. The first time, with nothing in your library yet, it opens first-time setup; after that it opens straight on your games, already in the order you last played them, and brings the list up to date in the background.
To quit, use any of these when no game is running:
- Hold B or Esc on the home screen for about 1.4 seconds. A bar fills after a quarter of a second; let go before it is full to cancel.
- Press Ctrl+Q.
- Choose Settings → System → Exit Moonglass.
Moonglass runs once at a time. Starting it again while it is open brings the open window forward.
Tip To start Moonglass with your computer, turn on Settings → System → Start Moonglass at login.
02
First-time setup
A short guide shown on the first start, from the Add your games card when the library is empty, and any time from Settings → System → First-time setup. Dots at the bottom show how far along you are. A chooses, B goes back; B on the first step skips setup. Finishing or skipping is remembered, so it never opens on its own again.
- Your stores. Moonglass looks for Steam, Epic, GOG, Battle.net and the Microsoft Store and shows how many games it found. Each store found on your computer has a switch, all on. Turn off any store whose games you do not want on the shelf (more on stores). The step opens with Continue selected, so a quick A never turns anything off. Up and down move; A or left and right flip a switch.
- Emulators (optional). Pick an emulator from the presets and add your ROM folders. See Emulators and ROMs.
- SteamGridDB key (optional). Enter a free key to get artwork for games your stores don't provide pictures for. See Artwork.
- Done. You land on your games. Artwork fills in as it downloads.
03
Controls
The hints along the bottom of the screen follow whatever you last touched: controller buttons after you use a controller, key names after the keyboard or mouse. Every hint is also a button you can click.
Home screen
| Action | Controller | Keyboard | Mouse |
|---|---|---|---|
| Move between games | D-pad or left stick | ← → | Wheel or touchpad swipe, one card per notch |
| Play | A | Enter or Space | Click the focused card |
| Focus a game | Click a card | ||
| Search | X | Just start typing | Click the search box |
| Game options | Y | Ctrl+O | Right-click a card |
| Switch filter | LB / RB | Tab / Shift+Tab, or PgUp / PgDn | Click a filter |
| First or last game | Home / End | ||
| Settings | Menu | Ctrl+, | Click the gear |
| Back, or clear search | B | Esc | The × in the search box |
| Exit Moonglass | Hold B | Hold Esc, or Ctrl+Q | |
| Window on or off | F11 | ||
| Add a program | Drop its file on the window |
Holding a direction repeats it, faster the longer you hold. The left stick has a round dead zone, so a slightly off-center stick doesn't drift.
Menus, lists and Settings
- Up and down move; left and right change a value; A / Enter selects; B / Esc goes back.
- In Settings, LB / RB or Tab switch sections.
- Anything highlighted can also be clicked; hovering highlights it.
Button names by controller
This guide uses Xbox names. On other controllers:
| Xbox | PlayStation | Switch Pro |
|---|---|---|
| A / B / X / Y | Cross / Circle / Square / Triangle | B / A / Y / X (by position) |
| LB / RB | L1 / R1 | L / R |
| View (two rectangles, left of the Xbox button) | Share (DualShock 4) or Create (DualSense) | − (Minus) |
| Menu (three lines, right of the Xbox button) | Options | + (Plus) |
04
The home screen
The shelf
Your games sit in one row. The focused game is about half the screen tall, outlined, with a soft glow in the colors of its artwork and its logo (or title) above it, along with a small badge for where it comes from. The other games are smaller and slightly darker.
Games are ordered by when you last played them, most recent first. Games you have never played follow, newest additions first, then by title (ignoring a leading "The", "A" or "An"). On the first start, Steam's own record of when you last played is used, so the order already matches your history.
If your library is empty, a single Add your games card opens setup.
Filters
The filters at the top left narrow the shelf. A filter with nothing in it is hidden.
- All
- Every game. Always shown.
- Recent
- Games played within the last 30 days. Change it to 7 or 90 days in Settings → Library.
- Favorites
- Games you starred from their options.
- Steam · Epic · GOG · Battle.net · MS Store
- Games from that store.
- Apps
- Programs you added yourself.
- Emulators
- Games from your ROM folders.
Top right
The search box, your controller's connection and battery (four levels, or "wired"), the clock, and the Settings gear.
What a card can show
- A star for a favorite.
- A Hidden tag, when hidden games are shown.
- A green dot with a number: Steam friends playing it right now (Steam friends).
- In use: a borrowed Steam game whose owner is playing it (Borrowed games).
- Below the card, depending on Card details: nothing, the title, or the playtime and source.
The background
Behind the shelf, Moonglass shows the focused game in one of four ways, set in Settings → Appearance → Background:
- Color bloom
- A blurred, tinted version of the game's art. The default.
- Full-screen art
- The game's wide art, sharp, across the whole screen.
- Full-screen art + motion blur
- The same, with sideways streaks. When you move, the next game's art slides in from that side and sharpens as it settles.
- Pure black (OLED)
- Black, with only the glow. Kind to OLED screens.
The glow pulses slowly and stops when another window has the focus. Turn it down or off with Glow.
05
Search
- Press X (the on-screen keyboard opens at the bottom), start typing on a keyboard, or click the search box.
- The shelf filters with each letter. Search looks at every game, whatever filter was on.
- Press Done on the on-screen keyboard (or Enter) to move to the results, then play as usual.
- B, Esc or the × clears the search and puts you back where you were.
Search ignores capitals, accents, punctuation and spaces, and matches any part of a title: half life, halflife and HALF-LIFE all find "Half-Life", and pokemon finds "Pokémon". Hidden and uninstalled games are not searched. With no match, the screen says so with what you typed.
06
Playing a game
Launching
Press A on a game. Moonglass shows Launching… and starts it the way its store would: Steam, Epic, GOG and Battle.net games start through their own client, Microsoft Store games through Windows, so achievements, cloud saves, Steam Input and the store's own playtime all keep working. Programs and emulators are started directly.
If the game takes a while, after 20 seconds the screen adds Still waiting… with B to cancel. A long wait is normal when the game's store (Steam, Epic and so on) is updating it first. After 3 minutes Moonglass stops waiting (change this in Settings → System → Stop waiting for a game after: 1, 3, 5 or 10 minutes).
While you play
Moonglass gets out of the way. It stays full screen behind the game, so you never see the desktop while the game opens. Either way it draws nothing and uses next to no resources, and the controller belongs to the game.
Returning to Moonglass mid-game
Press both sticks in and hold them for 2 seconds, or press Ctrl+Alt+Home. Moonglass comes forward on the Now Playing screen while the game keeps running behind it. You can also simply Alt-Tab to it.
The hold stops the combination from clashing with games that use those buttons. Change the buttons (both sticks pressed in, or View + Menu) and the hold time (1, 2 or 3 seconds) in Settings → System; the screen shows the names for your controller. Return to game on the Now Playing screen brings the game back in front, full screen again.
- The return combination works only while a game is starting or running.
- On Windows, the controller combination needs an Xbox-compatible (XInput) controller; other controllers can use the keyboard shortcut. The Xbox (Guide) button cannot be used: Windows and Steam claim it.
- On Linux the controller combination works with any controller. The keyboard shortcut depends on your desktop; Settings says whether it is available.
Now Playing
Whenever Moonglass is in front while a game runs, it shows Now playing with the game's name, how long this session has lasted, your total playtime for it, the time and your controller's battery (which a full-screen game hides), and the Quick Menu. It disappears as soon as the game ends.
Stopping a game
Choose Stop game in the Quick Menu (or press X / Del). Moonglass first asks the game to close normally, so it can save. If it is still running after 8 seconds, the button becomes Force stop, which ends it at once. Moonglass never stops a game unless you ask.
After the game
- Moonglass comes back to the front, usually within a second or two. A game that hands over to another program (a launcher starting the real game) gets 5 seconds of grace, so Moonglass doesn't jump back too early.
- If Steam, Epic, GOG Galaxy, Battle.net or Heroic popped up its window, Moonglass sends it back to the tray. The client keeps running so cloud saves finish. Turn this off with Send the store's launcher to the tray after a game.
- The session is added to the game's playtime, and the game moves to the front of the shelf.
- If Windows refuses to bring Moonglass forward, it flashes in the taskbar and shows a notification saying how to return.
07
The Quick Menu
A short menu on the Now Playing screen, like a console's guide button. Up and down move, A / Enter chooses. Moonglass never draws inside the game itself, so anti-cheat software has nothing to object to.
- Return to game
- Also B / Esc. Moonglass hides and you are back in the game.
- Save a clip
- Asks your capture tool to save the last moments of play. Shown when a tool is chosen.
- Take a screenshot
- Shown when your tool takes screenshots.
- Game volume
- Left and right change the game's own volume in 10% steps (not your system volume); A mutes or unmutes. Covers every sound the game and the programs it started make. Shows No sound from the game when it has none.
- Stop game
- Also X / Del. See Stopping a game.
Clips and screenshots
Moonglass doesn't record anything itself; it asks a tool that already records your game. Pick one in Settings → System → Clips and screenshots. The row under it tells you what the tool needs.
| Tool | System | Clip | Screenshot | What it needs |
|---|---|---|---|---|
| Xbox Game Bar | Windows (default) | Win+Alt+G | Win+Alt+PrtScn | "Record what happened" on, in Windows Settings → Gaming → Captures |
| NVIDIA Instant Replay | Windows | Alt+F10 | Alt+F1 | Instant Replay on, in the NVIDIA overlay |
| AMD Instant Replay | Windows | Ctrl+Shift+S | Ctrl+Shift+I | Instant Replay on, in AMD Software |
| gpu-screen-recorder | Linux | Signal to the recorder | None | Running in replay mode (-r) |
| Off | Linux (default) | Clip and screenshot rows are left out of the menu | ||
On Windows, Moonglass returns to the game, waits a moment, then presses the tool's shortcut; the tool shows its own confirmation over the game. Moonglass uses the tools' default shortcuts, so if you changed them in the tool, change them back. If a game runs as administrator and Moonglass doesn't, Windows blocks the shortcut and a notification says so.
08
Where games come from
Moonglass finds games on its own, at every start and whenever their folders change. It lists only games that are fully installed; it doesn't browse stores, buy, download or update games.
Steam
- Found automatically, in every Steam library folder. On Linux the native, Flatpak and Snap installs are all checked. If yours is somewhere unusual, pick it in Settings → Library → Steam folder.
- Tools and runtimes (Proton, Steam Linux Runtime, redistributables…) are left out. If another non-game slips through, choose Not a game (a tool): leave it out in its options; bring it back from Settings → Library → Steam apps that are not games.
- Games can get launch options, added to any the game already has inside Steam.
- With several Steam accounts on the computer, see Steam accounts.
Epic Games
- Windows: the games installed by the Epic Games Launcher. DLC, add-ons and Unreal Engine are left out.
- Linux: Epic has no official app, so Moonglass uses Heroic Games Launcher (native or Flatpak). Without Heroic, the Epic filter doesn't appear.
GOG
- Windows: every GOG game, installed with GOG Galaxy or with GOG's offline installers. With Galaxy installed, games start through it so its cloud saves and playtime keep working; without it, Moonglass starts the game's own program.
- Linux: through Heroic, like Epic.
- Add-ons are left out, and GOG's own full game names are used.
- On Windows, a GOG game installed while Moonglass is open appears after your next game, or after Rescan library now.
Battle.net
- Windows only: every game installed by Battle.net. Games start through Battle.net, so its sign-in and updates work as usual; if Battle.net asks you to sign in, do that once.
- A game Moonglass doesn't know how to ask Battle.net for yet starts through its own launcher program instead, which opens Battle.net with that game.
Microsoft Store and Xbox app
- Windows only: games from the Microsoft Store, including PC Game Pass games installed with the Xbox app. They start through Windows, as they would from the Start menu.
- Only games made with Microsoft's current game kit are found, which covers recent Store and Game Pass games; some older Store games are not.
- Battle.net and Store games have no free source of artwork: add a SteamGridDB key for covers, or they get a title card.
- A Battle.net or Store game installed while Moonglass is open appears after your next game, or after Rescan library now.
Turning a store off
Don't want a store's games on the shelf? Turn it off in Settings → Stores (Show Steam games, Show Epic games, and so on) or during setup. Its games disappear from the shelf, the filters and search. Moonglass still keeps track of them, so turning the store back on is instant and their favorites, playtime and artwork are intact. Each row shows how many games the store has, or that it wasn't found. Your own programs and emulated games are always shown.
09
Adding programs
Any game or program can join the shelf under Apps.
- Open Settings → Library → Add a game, or drop the program's file on the Moonglass window.
- In the file browser, choose the program: an
.exeon Windows; on Linux any executable file, including AppImages and scripts. - It appears on the shelf, named after its file. Artwork is looked up for it.
A Windows .exe on Linux needs a small script that runs it through Wine or Proton; add the script.
From the program's options you can add launch arguments, change the folder it starts in, and handle programs that start a launcher and exit (Launcher-style executable). If you delete the file, the game is hidden; it comes back if the file returns.
10
Emulators and ROMs
Tell Moonglass which emulator you use and where your games are; each game then has its own card.
Adding an emulator
- Open Settings → Emulators → Add an emulator (or the emulator step of setup).
- Pick a preset, or Another emulator for anything with a command line.
- Choose the emulator's program in the file browser. On Linux, a preset whose Flatpak is installed says so and is set up without asking.
- Add a ROM folder and type its platform name (for example GameCube). The name shows on the cards.
| Preset | Arguments | Files |
|---|---|---|
| RetroArch | "{rom}" | .zip .7z .nes .sfc .smc .gb .gbc .gba .md .gen .n64 .z64 .nds .cue .chd .m3u |
| Dolphin | -b -e "{rom}" | .iso .rvz .gcm .gcz .ciso .wbfs .wad |
| PCSX2 | -batch -fullscreen -- "{rom}" | .iso .chd .cso .cue .m3u |
| RPCS3 | --no-gui "{rom}" | Game folders containing PS3_GAME/USRDIR/EBOOT.BIN |
| Ryujinx | --fullscreen "{rom}" | .nsp .xci .nro |
| Eden / Citron / yuzu | -f -g "{rom}" | .nsp .xci .nro |
| Another emulator | "{rom}" | You choose |
RetroArch Without a core, RetroArch asks which to use. To skip that, add -L <core> to the arguments, for example one emulator profile per system.
Arguments
The arguments are passed to the emulator after its program. Three placeholders are filled in for each game:
{rom}- Full path to the game file or folder.
{rom_dir}- The folder the game is in.
{rom_name}- The file name without its extension.
Put quotes around a placeholder, as in -e "{rom}". Arguments never pass through a shell, so paths with spaces or odd characters are safe.
Managing an emulator
Select an emulator in Settings → Emulators to change its program, arguments or file types, add another ROM folder, or remove a folder or the whole emulator. Removing asks for a second press.
How games are found in a ROM folder
- Subfolders are included.
- A
.m3uplaylist is one game, and the discs it lists are not shown separately. A.cuehides its.binfiles. - Folder-based games (PS3) are found by the marker file in the profile.
- Switch updates and DLC are left out.
- Titles drop the tags at the end of a file name: Hades [0100535012974000][v0] becomes Hades. Disc numbers are kept.
Since each folder belongs to one emulator, two emulators that both accept, say, .iso never get confused.
11
Per-game options
Press Y, Ctrl+O, or right-click a card. What's listed depends on the game.
- Play
- Start the game.
- Join name
- Steam games, when a friend is in a session you can join. See Steam friends.
- Add to favorites / Remove from favorites
- Favorites get a star and their own filter.
- Hide from library / Show in library
- Hidden games leave the shelf and search. Show them again with Settings → Library → Show hidden games.
- Change artwork…
- Pick your own image. See Artwork.
- Use automatic artwork
- Shown once you've changed the artwork; goes back to the automatic picture.
- Launch options / Launch arguments
- Extra arguments for the game, typed on the on-screen keyboard. For Steam games these are added to the game's launch options inside Steam. Programs and emulated games get them after everything else. Not available for Epic and GOG games, whose clients don't accept any.
- Working directory
- Programs only: the folder the program starts in. By default, its own folder.
- Launcher-style executable
- Programs only. Turn on for a program that starts the real game and then closes, so Moonglass watches the game's folder instead of the program. Ignored for a program in a folder shared with others (a drive, Downloads, the Desktop…).
- Process to watch
- The name of the game's real program (with or without
.exe), for games whose program lives outside their folder, such as games started through another launcher (EA, Ubisoft, Rockstar). Leave it on automatic otherwise. - Not a game (a tool): leave it out
- Steam only. Removes a Steam tool from the shelf. Asks for a second press.
- Remove from Moonglass
- Programs and emulated games. Asks for a second press. Store games can't be removed (uninstall them, or hide them).
12
Artwork
Each game gets a cover, a wide background picture and, where there is one, a logo. Moonglass tries these sources in order and keeps the first picture it finds of each kind:
- Your own picture, if you chose one.
- Steam's own pictures on your disk, for Steam games. No internet or key needed.
- Epic's catalog, for Epic games on Windows. No key needed.
- GOG's catalog, for GOG games. No key needed.
- SteamGridDB, for any game, if you entered a key.
- Game databases for emulated games: Switch icons and banners by the game's ID, and the libretro box-art collection for older systems. No key needed. Switch games are recognized by the ID in the file name, or from the games your Ryujinx-family emulator has already run.
- A title card with the game's name on a color gradient, when nothing else is found.
Games left with a title card are tried again each time artwork is refreshed.
Getting a SteamGridDB key
- Sign in at steamgriddb.com (free) and create an API key in your profile's preferences.
- Enter it in Settings → Artwork → SteamGridDB API key, or during setup.
- Choose Refresh all artwork.
The key stays on your computer and is never written to the logs.
Using your own picture
- Open the game's options and choose Change artwork….
- Pick a
.png,.jpgor.webpfile in the file browser.
Your picture is never replaced by a refresh. Use automatic artwork undoes it.
How art fits a card
Cards can be posters (2:3), banners (16:9, using the wide picture) or squares (1:1), set by Card shape. When a game's picture has a different shape (a square Switch icon on a poster card), Card art decides:
- Fit whole art
- The whole picture, over a blurred fill made from itself. The default.
- Zoom to fill
- Cropped from the center to fill the card.
- Original shape
- The card takes the picture's own shape, as large as fits.
13
Steam accounts and friends
Switching Steam account
On a shared PC, Settings → Library → Steam account lists the accounts Steam remembers, the signed-in one marked. Choosing another closes Steam, sets it to sign in with that account, starts it again in the background and waits up to 90 seconds for the switch. No password is involved: Steam uses the sign-in it saved. Accounts whose password Steam didn't save are marked; if the saved sign-in has expired, Steam shows its own sign-in window and Moonglass tells you the switch didn't finish. Not available while a game runs. Switching in Steam itself is followed too.
Only games this account can play
With several accounts, Only Steam games this account can play (on by default) hides installed Steam games the signed-in account has no license for, counting games shared through its Steam Family. Free-to-play games the account has never run on this PC can't be recognized; turn the setting off to see everything. It does nothing when only one account is known.
The playtime shown for Steam games is the signed-in account's, so it changes with the account too.
Steam friends
See which friends are playing your games, and join them.
- Create a Steam Web API key at steamcommunity.com/dev/apikey.
- Enter it in Settings → Library → Steam friends: Web API key.
- Cards show a green dot with the number of friends in that game, and the focused game names them ("Alex and Sam are playing").
- When a friend's session can be joined, the game's options offer Join with their name.
- The Friends row in Settings shows how many friends were found and how many are playing, or why it didn't work.
- Moonglass checks once a minute, and not at all while you play. Friends who appear offline or have a private profile aren't shown. Epic, GOG, Battle.net and the Microsoft Store offer nothing similar.
- The key is sent only to Steam and never logged.
Borrowed games
If a Steam game installed from someone else's library is being played by its owner, its card says In use with their name. The first press of Play explains this; press again to start anyway (your family may own another copy). Only owners who are also your Steam friends can be noticed.
14
Settings reference
Open with Menu, Ctrl+, or the gear. Changes apply at once and are saved. Defaults are in bold.
Appearance
| Setting | Values |
|---|---|
| Card shape | Posters (2:3) · Banners (16:9) · Squares (1:1) |
| Card art | Fit whole art · Zoom to fill · Original shape |
| Focused card size | Normal · Large · Extra large |
| Card spacing | Compact · Normal · Wide |
| Card details | Art only · Art + title · Art + playtime & source |
| Background | Color bloom · Full-screen art · Full-screen art + motion blur · Pure black (OLED) |
| Background blur | Light · Medium · Strong |
| Glow | Off · Subtle · Normal · Bright |
| Startup animation | On · Off. The name, then the cards rising in, about 1.5 seconds. |
| Reduced motion | On · Off. Turns off the glow pulse, the startup animation and every transition. |
| Clock | 24-hour · 12-hour |
Library
| Setting | What it does |
|---|---|
| Add a game | Add a program. See Adding programs. |
| Recent shows games played within | 7 days · 30 days · 90 days |
| Show hidden games | On · Off. Hidden games come back on the shelf with a Hidden tag. |
| Rescan library now | Look for new and removed games straight away. |
| Library | How many games you have, and how many are hidden. |
| Steam account | Switch account. See Steam accounts. |
| Only Steam games this account can play | On · Off |
| Steam folder | Found automatically, or a folder you pick. |
| Steam apps that are not games | The Steam apps you marked as not games. Select one to put it back. |
| Steam friends: Web API key | See Steam friends. |
| Friends | What the friends feature last found. |
Stores
| Setting | What it does |
|---|---|
| Show Steam / Epic / GOG / Battle.net / Microsoft Store games | On · Off, with how many games each store has. Battle.net and the Microsoft Store are Windows only. See Turning a store off. |
Emulators
One row per emulator, plus Add an emulator. See Emulators and ROMs.
Artwork
| Setting | What it does |
|---|---|
| SteamGridDB API key | Enter or clear your key. |
| Refresh all artwork | Download artwork again for every game (your own pictures are kept). |
| Sources | Where artwork comes from. |
System
| Setting | What it does |
|---|---|
| Display | Fullscreen · Borderless window · Window. F11 switches to a window and back. |
| Fullscreen resolution | Shown in Fullscreen, on Windows. Desktop or any resolution your screen supports. It's used only while Moonglass is in front: your games and desktop keep their own resolution. |
| Start Moonglass at login | On · Off |
| Send the store's launcher to the tray after a game | On · Off |
| Return to Moonglass during a game | The combination for your controller, and whether the keyboard shortcut is available. |
| Return to Moonglass: buttons | View + Menu · Both sticks pressed in |
| Return to Moonglass: hold for | 1 second · 2 seconds · 3 seconds |
| Clips and screenshots | Off · the tools for your system. Xbox Game Bar on Windows, Off on Linux. See Clips and screenshots. |
| Saving clips | What the chosen tool needs. |
| Stop waiting for a game after | 1 minute · 3 minutes · 5 minutes · 10 minutes |
| First-time setup | Run setup again. |
| Logs | Where the log files are. |
| Version | The Moonglass version. |
| Updates | Check for a new version, install it, then restart into it. Betas get newer betas and final releases; a final release gets final releases only. |
| Check for updates at startup | On · Off. Says something only when there is a new version. |
| Exit Moonglass | Quit. |
15
Typing and picking files
On-screen keyboard
Appears at the bottom of the screen for search and every text field (keys, arguments, process names, file types, platform names). Its last row has the characters arguments and paths need: { } " / \ : _ = + @.
| Action | Controller | Keyboard |
|---|---|---|
| Type the highlighted key | A | Type normally |
| Delete | X | Backspace |
| Space | Y | Space |
| Done | Menu | Enter |
| Cancel | B | Esc |
Keys can also be clicked. Shift switches to capitals.
File browser
Used whenever Moonglass needs a file or folder. It starts at your home folder and your drives (Windows) or mounted volumes (Linux), and shows only the kind of file being asked for. Open folders with A; go up with B or Backspace (at the top, that closes the browser). Typing a letter jumps to the next entry starting with it.
16
Your library and playtime
Staying up to date
Moonglass checks for new and removed games at every start, after each game, and whenever a store's or ROM folder's files change (a couple of seconds after). Use Rescan library now to force it.
An uninstalled game is hidden, not forgotten: reinstall it and its favorite star, playtime and custom artwork are still there.
Playtime
Moonglass counts the time you play from the moment the game is running until it closes; updates and launcher screens don't count. For Steam games it also reads Steam's own count for the signed-in account, which includes play outside Moonglass and on other PCs, and shows whichever is larger (the two are never added, since Steam's already includes Moonglass's sessions). Epic and GOG keep their counts online only, so for those games you see Moonglass's own count.
Safe by design
Your library is checked every time Moonglass starts, and a copy of the last good version is kept. If the file is ever damaged, Moonglass restores that copy (or, without one, starts fresh and finds your store games again) and tells you on the first screen. The damaged file is set aside, never deleted.
Where things are stored
| Windows | Linux | |
|---|---|---|
| Library and settings | %APPDATA%\Moonglass\ | ~/.local/share/moonglass/ |
| Artwork | %LOCALAPPDATA%\Moonglass\cache\ | ~/.cache/moonglass/ |
| Logs (kept 7 days) | %LOCALAPPDATA%\Moonglass\logs\ | ~/.local/state/moonglass/ |
On Linux these follow the XDG_* variables when set. moonglass paths prints them.
17
Command line
Run moonglass with no arguments to open it. With a command, it works in the terminal instead, which is handy for scripting and for checking how a game is detected. <game> is a game's ID (like steam:620) or its number in moonglass list.
| Command | What it does |
|---|---|
list [--filter <filter>] [--search <text>] | Scan, then list games in shelf order. Filters: all, recent, favorites, steam, epic, gog, battlenet, msstore, apps, emulators. |
scan | Scan and report what changed. |
launch <game> [--epic-fallback] [--give-up <secs>] | Start a game and report each step until it closes. |
add-exe <path> [title] | Add a program. |
add-emulator <id> <name> <program> <arguments> <extensions> [folder-marker] | Add an emulator profile. |
add-rom-dir <path> <emulator-id> <platform> [--flat] | Add a ROM folder (--flat: no subfolders). |
remove <game> | Remove a program or emulated game. |
favorite <game> on|off | Star or unstar. |
hide <game> on|off | Hide or show. |
options <game> [--args <a>] [--cwd <dir>] [--watch <process>] [--track-folder] | Set per-game options. |
artwork [--force] | Fetch missing artwork, or all of it. |
set-art <game> <image> | Use your own picture. |
unlock-art <game> | Back to automatic artwork. |
sgdb-key <key>|clear | Set or clear the SteamGridDB key. |
steam-signal <game> [--secs <n>] | Compare Steam's "running" flag with Moonglass's detection, once a second. |
steam-accounts | List Steam accounts and what the signed-in one can play. |
steam-switch <number> | Switch Steam account (restarts Steam). |
autostart on|off|status | Start at login. |
paths | Show where data, artwork and logs are. |
Environment variables
MOONGLASS_WINDOWED=1- Open in a window instead of full screen.
MOONGLASS_LOG=debug- More detailed logs.
18
Troubleshooting
- A game is missing.
- Check that it's fully installed and that its store is turned on (Settings → Stores), then choose Rescan library now. For Steam in an unusual place, set Steam folder. On Linux, Epic and GOG need Heroic. Also check Show hidden games and, with several Steam accounts, Only Steam games this account can play.
- Moonglass comes back while I'm still playing, or never comes back.
- Some games run from a program outside their folder, often through another launcher. Set Process to watch in the game's options to the name of the game's real program (Task Manager shows it). For a program that starts a launcher and exits, turn on Launcher-style executable.
- The game started but Moonglass is still on Launching.
- Same fix: set Process to watch. You can cancel with B once Still waiting… appears.
- Moonglass doesn't come back to the front after a game.
- Use the return combination, Alt-Tab, or click it in the taskbar. On Linux under Wayland, the desktop may refuse; a notification tells you how to return.
- Holding View + Menu opens Task View instead of Moonglass.
- Windows is treating View + Menu as the Xbox button, and holding that opens Task View. Either switch the buttons back to both sticks in Settings → System, or turn off Use View + Menu as Guide button in apps in Windows Settings → Gaming → Xbox Game Bar.
- Holding the return combination does nothing during a game.
- On Windows it needs an Xbox-compatible controller; use Ctrl+Alt+Home otherwise. Make sure you hold for the full time set in Settings → System.
- Save a clip does nothing.
- Check that your tool's recording is switched on (the Saving clips row says how), and that you haven't changed its shortcut. A game running as administrator blocks the shortcut.
- A game shows only its name, not artwork.
- Add a SteamGridDB key and choose Refresh all artwork, or set your own picture from the game's options.
- A Steam tool or soundtrack appears as a game.
- Open its options and choose Not a game (a tool): leave it out.
- An Epic game won't start.
- A few titles need Epic's longer launch form. Try
moonglass launch <game> --epic-fallback. - A Steam, Epic or Windows window needs a mouse.
- Prompts owned by other programs (license agreements, cloud-save conflicts, administrator prompts) can't be controlled by Moonglass. Use a mouse or keyboard, then return with the combination.
- Something else is wrong.
- Start with
MOONGLASS_LOG=debug, reproduce the problem, and report it with the log (Settings → System → Logs shows where it is).