Clarity 1.19.0

The CRT face has its own place now

It was buried behind a command-line flag. There is a CRT Mode section in the Control Panel, with the two things you would want in it: a button to launch it, and a button to put it in your system menu on its own.

That second one is separate from "Add to Application Menu" on purpose. That writes Clarity and Couch together, which is what nearly everyone wants. The machine plugged into a tube TV is usually not the machine you sit at, and a 480-line face in the menu of a desktop that will never show it is just clutter.

DOOM CE

The PSX Doom and PSX Final Doom total conversions, rebuilt to use what modern GZDoom can do. Both want doom2.wad, which your library already links like it does for any other Doom mod. They need UZDoom 5.0.0 or newer, so the UZDoom recipe now points at the 5.x download, which renamed its file to Windows-UZDoom-Release-x86_64.zip with no version in it.

Doom 64 CE is deliberately not included, even though it is published in the same place under nearly the same name. It needs the Doom 64 WAD from Steam, which cannot be used as it ships: the mod carries a script that patches it first. Nothing here can link an IWAD that has to be generated by running a Windows script, so a recipe for it would install cleanly and leave you with something that will not start.

Road Rash, from your own disc

Point Clarity at a backup of the disc and it installs. Four separate faults stood in the way, each one hiding the next, and all of them come from copying a disc rather than running the installer that came on it.

The game imports AWEMAN32.DLL, which does not sit beside the game: it is in SETUP/, and the Windows installer copied it into place. Without it the import fails before a window exists, and you see nothing happen at all.

Then it asks the display to become 640x480, which a modern multi-monitor setup refuses, and the game treats that as fatal. Then it looks for a CD-ROM drive and finds none, because the disc is now a folder. Then it looks for the record the setup program writes, one string under Electronic Arts\RoadRash 95, and gives up without it.

All four are settled when you press play. No wizard, no Windows 95 warning to click past, nothing to copy by hand.

The disc's own installer is not used, and the small "setup" download that usually comes with these backups is deliberately ignored: it is an Inno Setup executable, which nothing here can open, and unpacked it is a file called RoadRash.exe that would happily install itself under the game's name.

A Recipe can name a resolution

env, settings and wrapperExceptions describe what a game needs. scale describes what it cannot be argued out of.

Games from the mid-nineties ask for 640x480 and draw into the corner of anything larger. A game that names its resolution is handed to gamescope, which gives it exactly the small display it asked for and scales the picture up to fill the screen. That is also why the display error goes away: the mode change is no longer aimed at a monitor that refuses it.

Integer scaling and nearest-neighbour, so the pixels stay square rather than turning to soup, and pillarboxing rather than stretching a 4:3 game across an ultrawide. Where gamescope is not installed the game still runs, just small.

Two things that only showed up on a clean machine

A game installed from a disc has no prefix until the first time you press play, and the launch fix was mapping its CD drive before building it. That left the prefix half-existing, in which state wineboot makes no progress at all: 4KB and nothing after ninety seconds, against a working 633MB prefix in seven seconds from nothing. So none of the registry work landed on a first run and the game only worked on the second. Measured both ways; the fix is to build first and map second.

And closing the Manager window did not quit Clarity. Quitting was left to window-all-closed, which only fires once every window is gone, and this app opens several that outlive their usefulness: a manual, a store login, the PICO-8 browser. Any one of them still alive and the process kept running behind a window you had closed, and the next launch met the single-instance lock and looked like it did nothing. Closing the Manager now quits Clarity however the window was closed, including with the compositor's own keybinding.

window-close also acted on whichever window happened to be focused when the message arrived rather than the one that sent it, so with focus moved elsewhere it closed the wrong window, or nothing at all.

Clarity 1.18.0

A third face, for a tube TV

Clarity has had two faces: the Manager, for a desk, and Couch, for a sofa and a modern panel. Neither works on a CRT. At 720x480 interlaced, over composite, a cover is about 90 pixels wide and does not survive chroma subsampling, so an art-led browser has nothing to show. The CRT face is a menu instead: a row of text is the interface, and art is only there to tell two similar rows apart.

The whole interaction is Up, Down, A to descend, B to go back, which is the vocabulary a D-pad has and the one a TV menu has always had. Arrow keys and Enter work too.

The constraints are in the stylesheet as constraints rather than taste. Nothing thinner than 4px, because a 1px rule on an interlaced display is drawn by one field and not the other and strobes at 30Hz. Square corners, since a radius here is four aliased pixels pretending to be a curve. No transitions, because interlace smears motion. One bright thing on a dark ground, which keeps average beam intensity and so phosphor wear low. Everything sits inside a title-safe box, because every set crops a different amount.

It is not a menu that hands off to a desktop. You stay in it: install and uninstall GOG and Epic games, scrape artwork and details, search, filter by store, make and edit playlists, mark favourites, set graphics compatibility, and launch. Colours are theme tokens fed by the shared Omarchy bridge, live, so omarchy theme set restyles it while it is open.

The Witcher: Enhanced Edition launches

Pressing Play did nothing at all. No window, no error, no log.

Both GOG's launcher.exe and the game's own witcher.exe read InstallFolder under HKLM\Software\CD Projekt RED\The Witcher before they do anything else, and neither has a fallback. gogdl downloads the depot and never performs the registry step GOG's installer would, so the value is absent and both give up: the launcher exits 0 without drawing a window, which is why nothing anywhere reported a failure.

The value is now written into the prefix at launch, in the WoW64 view those 32-bit executables actually read, and rewritten if the game is ever moved. The language is set at the same time, without which the menus have no text in them at all.

Soundtracks for Doom mods

Built from the re-release you already own, with the source found by content rather than only by title.

A game no longer dies when the face that started it quits

Couch and the CRT face capture a game's output for a few seconds so a launch that fails on the spot can say why, which on a TV is the difference between a dead end and something you can act on. That capture used a pipe, and a pipe's read end belongs to the face. Quitting the face closed it, and the game died of EPIPE on its next write to stdout, which native games do constantly.

Measured with a child that logs once a second and a parent that exits at three: through a pipe the game managed four ticks and stopped; through a file it ran on to eighteen and was still going. The output now goes to a temp file that is unlinked the moment it is open, so the game outlives the face, nothing has to clean up after it, and the space returns when the game exits.

Four more, in the CRT face

An answer that arrives late now belongs to the screen that asked for it. Every action waits on the main process while the face stays live, so pressing Escape during an uninstall used to leave the library screen underneath overwritten in place by the game screen, a level short, with a breadcrumb naming neither. Twenty-one handlers could do that.

Enter is not debounced anywhere, and these screens sit still for minutes, so pressing it twice asked the engine to install one game twice. Install and uninstall now hold a lock for their duration.

The root screen refreshes like every other screen. It was assembled by hand at boot without the field pop() needs, so it was the one screen that never rebuilt, while carrying the most state that moves: Continue names the last game played, Library carries the filtered count, Filters and Install carry summaries. Change a filter, press Escape, and the counts underneath still described the library from before.

Install and uninstall now say so when the library write fails. The files are already on disk by then, so a failed write is not a failed install: it is a library that disagrees with the disk, and it used to be discarded silently.

A game's blurb is remote HTML

The Steam description pane was filled by assigning the stored description straight to innerHTML. That text is markup fetched from the store API and written by whoever publishes the game. A <script> assigned that way never executes, which is most likely why it looked safe, but <img onerror> executes perfectly well.

It is now parsed and rebuilt from an allowlist: known tags keep their text, script, iframe, svg, object and form are dropped outright, every attribute outside the allowlist goes, and src and href must be http(s), which disposes of javascript: and data: as well. Steam's own formatting survives intact. Checked against a real description: 2,489 bytes in, 2,140 out, its eight paragraphs and two images kept, and no handler or script left anywhere in it.

Clarity 1.17.0

Arcanum, and a Recipe that could not fire

Arcanum: Of Steamworks and Magick Obscura closed the instant it launched. No window, no error.

GOG's build ships DDrawCompat as ddraw.dll. Clarity's general rule is to hand a game the wrapper it shipped with, which is exactly right for Resident Evil 2's Classic REbirth and for Quake's 3dfx driver. DDrawCompat fixes this 2001 game on modern Windows by hooking DirectDraw's own internals, and it cannot survive those hooks under Wine, so the general rule was what killed it. Measured on one machine, same prefix, same Proton build: with the shipped wrapper the game produced no window at all in 26 seconds; on Wine's own library it ran with a visible window for 22 of those 26.

A Recipe can now name a wrapper that has to stay shadowed, and Arcanum is the first game to use it. DDrawCompat.ini is left on disk untouched.

Finding that out turned up something worse. The launch path used the Recipe catalogue without ever importing it, and both call sites sit inside a try/catch, so the error was swallowed and logged as "per-game fix skipped". Every per-game Recipe has been a no-op in that path, including OutRun 2006 and Resident Evil 2, and 1.16.0 shipped that way. One line puts it back. The proof is Arcanum launching through the real engine: 29 of 32 seconds with a window, where before there was none.

docs/RECIPES.md now writes down what a Recipe is, what one may carry, where they live, and how to add one.

Library Report

Your library as something worth looking at: a web page, a PDF, or images sized for posting. Sixteen sections covering what you own, what you play, genres, stores, the backlog, ratings, decades, studios, franchises, how much of it runs on Linux, and more. Every section can be switched off, so the report is only what you want to show. Three themes, four layouts, and the art comes from your own library.

It has its own section in the Control Panel.

Add a Steam game Steam will not report

Mods published on Steam are the clearest case. Adding Enderal: Forgotten Stories to your Steam library grants no licence the API reports, so it is absent from every sync, and until it is installed there is no local manifest either. No import could ever find it.

Connections now has "Missing a game Steam does not list?". Give it a name, an App ID or a store link: a name searches the store and offers the matches, an ID or link goes straight in. The game arrives with artwork, description, genre, studio, year and ProtonDB tier, and Install works from there. Games added this way are remembered, so the next sync keeps them instead of deciding Steam no longer knows them.

Batch Scrape, installed games only

Batch Scrape Missing Data can now be pointed at your installed games rather than the whole library.

Clarity 1.16.0

A bare .pk3 is selectable again

Brutal Doom has always installed from a bare .pk3 as well as from its zip, and the recipe even says so, but the file picker only offered zip, 7z, rar, exe, tar, gz and xz, so you could not actually pick one. The picker now asks the catalogue which formats it accepts, so it widens on its own the next time a recipe brings a new one.

ECWolf takes Super 3D Noah's Ark and the Spear of Destiny demo

ECWolf names every data format it accepts, and two were missing from what Clarity looked for: .n3d for Super 3D Noah's Ark and .sdm for the shareware Spear of Destiny. Point ECWolf at either and it now links the data like it does for Wolfenstein 3D.

The Linux edition

This is the first release since macOS moved to its own repository, Clarity-Mac, where it keeps its own releases. The macOS code that no longer ran here is gone, about three thousand lines of it. Nothing changes for you on Linux, and that was checked rather than assumed: this build and 1.15.3 were run side by side on a copy of the same library and came out identical.

Clarity 1.15.3

Fallout: London One-click Edition now starts

It installed perfectly and then played its music over a black screen, put up a warning about loose files, and opened a Nexus page in your browser.

GOG's installer performs finishing steps after the files land, and nothing on Linux performed them. The plugin list never reached the game, so none of London ever loaded, and loose file loading stayed switched off.

Both are now done at launch, repairing the install you already have. No reinstall, no reconfiguring.

One detail worth knowing if you ever hit this by hand: the setting that turns loose files on had to be written somewhere other than the file GOG writes it to, which is exactly why it looked like it was already set.

Seventh entry on the Game fixes list.

Clarity 1.15.2

Couch Mode, from using it.

Fullscreen survives a game

Couch came back from a game tiled instead of fullscreen, which breaks the whole point of it.

The cause turned out to be broader than launching a game: any window opening on that workspace drops Couch out of fullscreen, and the compositor never puts it back when that window closes. A game is simply the window you notice. Couch now re-asserts fullscreen the moment it gets the screen back, without waiting for you to press the wake combo.

The jukebox footer is no longer cut off

With a long track list the controls at the bottom were clipped off the edge entirely. The jukebox panel was being drawn taller than the screen it sits in, by exactly its own padding, and everything below the fold was thrown away. It now fits, and the footer can no longer be squeezed by the list above it.

The gamepage button says PLAY after installing

Install a game with its page open and the button went on saying INSTALL for something already installed. The page now re-reads the game when the library changes, without restarting the trailer or the pan behind it.

No more emoji

Nine of them, including the arrow on the install button, the clapper board on the trailer button and the padlock on locked achievements. They did not fit.

Clarity 1.15.1

Two bugs found by auditing the code.

An AppImage without its executable bit took the whole app down

spawn reports a missing or non-runnable binary through an asynchronous error event, never a throw, so a try/catch never saw it, and an unhandled one is fatal. The existence check passed happily, because existsSync answers true for a file with no executable bit, and then launching it killed the Manager on the spot.

An AppImage downloaded without +x is the commonest mistake there is, and Launch EmuLatte walked straight into it. PICO-8 and the terminal launcher had the same shape. All three now report the failure instead of dying.

Desktop shortcuts wrote unquoted arguments

A shortcut whose argument contained a space split in two the moment anything read the line back, and a literal % was swallowed rather than escaped as the freedesktop spec requires. Nothing in the shipped app passes such an argument today, so this one was latent rather than biting, but it is a shared helper and the next caller would have hit it.

Clarity 1.15.0

Both platforms on the same number for the first time since 1.13.1.

macOS: Windows Steam games through CrossOver

Windows Steam games installed into a CrossOver bottle are now found and launched like any other Steam game, and tagged so they do not read as native. This is the feature 1.15.0 exists for.

Clarity does not install Windows Steam, or the games. You set those up in CrossOver yourself and Clarity finds what is already there and runs it. Mac-Native and CrossOver are opposites and both can be true of one game at once: one says there is a real macOS build, the other that there is a Windows build reachable through the bottle.

⚠️ macOS jumps 1.13.1 to 1.15.0. There was never a macOS 1.14.0: the Mac downloads on that release are the 1.13.1 builds, renamed.

Linux

The launch log prints the command it actually ran. The header line joined the arguments with spaces, so any path containing a space printed as two arguments that never existed, and a game that died on the spot pointed you at a quoting bug that was not there. The launch itself was always correct. Every game with a space in its install path logged the same thing.

The theme picker names your desktop theme. The entry read OMARCHY, which is not a name anyone chooses a theme by. It now reads whatever your desktop is wearing, and the button says "Wearing tokyo-night" rather than "Matching your Omarchy theme", so it tells you which rather than restating what the highlight already shows.

Nothing changes for Linux from the CrossOver work

Nine lines of no-op stubs, so callers can ask about bottled Steam on any platform without branching. The reconcile pass runs everywhere but cannot write to a Linux library: no Linux row can hold a steambottle:// command, so every row is skipped. Checked rather than assumed.

Clarity 1.14.0

Manage Storage stops being a read-only screen.

move and delete, per game

Every row in Control Panel → Library → Manage Storage now carries two buttons. The screen already told you what was eating the disk; now it can do something about it.

Move opens a destination picker in the shape Steam uses: every writable filesystem the machine actually has, read from /proc/mounts rather than a hardcoded list, each showing what is free on it. A drive with less room than the game is marked, so a 69.9GB game shows a 69.7GB drive in red instead of letting you start a move that cannot finish. There is a folder picker underneath for anywhere the list does not cover.

Within one filesystem it is a rename, so it is instant whatever the size. Across drives it copies with byte progress and then removes the original, and a copy that fails takes its half-written destination with it rather than leaving something that reads as installed.

Delete names the game, the folder and the bytes it frees, and says plainly what it does not touch. GOG and Epic titles go through the store engine's own uninstall; anything else has its folder removed. Both end marked uninstalled in library.db and games.db.

A move repoints every place the folder is written down, not only install_path: LaunchCommand and LaunchCommands for games that are not GOG or Epic, and game_manuals.path for a manual living inside the game folder. Updating the first and not the others is how a moved game becomes unlaunchable.

fixed

The migration script only looked in one of the two places the database can live. findInstallerDb has two candidates: the engine's own userData, and InstallerConfig beside the app data. The script migrated the first and ignored the second, so an install using the second was left with its real database behind under the old name, where nothing looks for it, and the next sign-in created an empty one beside a full games directory it could no longer see. That is the exact failure the script exists to prevent.

It now migrates both, in the order the app itself reads them, and renames the whole InstallerConfig directory in one go rather than file by file, because the engine resolves gogdl_auth.json and the wine prefixes from the database's own directory and they have to travel together. Found on macOS, but the same two-entry list exists on Linux, so it was never a macOS-only hole.

The unquarantine command in the macOS guide named an app that does not exist. The bundle is Clarity Game Manager.app, not Clarity.app, so the command failed for anyone who got that far, which is the step you only reach when the other two have already not worked.

macOS

Clarity-1.13.1.dmg and Clarity-1.13.1-arm64.zip are attached here so they are on the current release rather than buried in an older one. They are the 1.13.1 build: the Mac cannot be packaged from Linux, so it is one version behind and does not yet have the Manage Storage buttons. The filenames say so rather than leaving you to find out after downloading. Rebuilding on the Mac with npm run dist:mac brings it level.

First launch needs one step, because the build is unsigned:

xattr -dr com.apple.quarantine "/Applications/Clarity Game Manager.app"

also

macOS shipped alongside Linux for the first time in 1.13.1, and its builds are attached above.

Download: Clarity.AppImage, chmod +x and run. Manager by default, --couch for the couch, installer for the headless CLI.

Clarity 1.13.1

A patch on top of 1.13.0. The 1.13.0 asset stays as it was published, because the version is baked into the binary and two builds answering to the same number is a debugging problem you only get to have once.

fixed

The bar plugin's "Find a game" row did nothing. It asked an injected shell object to toggle the overlay, but the bar host does not hand a bar widget that object. The property stayed null, the guarded call fell straight through, and nothing errored, so it read as a dead button rather than a bug. It goes through omarchy-shell shell toggle now, the same IPC call SUPER+CTRL+G is bound to, so it still starts no second copy of anything.

A startup crash on macOS. darwin.js exports displayPicker as null, because the window-rule engine behind it is a KWin feature. The Manager read it unguarded and then called .configure() and .isSupported() on the result. Its own comment already recorded that a missing null check here "was an instant crash on this host once already". The fix existed on the mac branch and had never come back to main.

package-lock.json had drifted to 1.9.3 while package.json moved on.

changed

The About button on the rail was a two-letter text monogram left over from an older name. It wears the aperture now, in the accent colour.

The fullscreen pill carried an inline SVG still drawn in the old brown palette. Same mark, and the label is just Go Fullscreen. The command palette entry follows it.

Couch Mode's splash and home header both read CLARITY.

Both marks use currentColor, so they take whatever theme is applied rather than carrying colours of their own.

Download: Clarity.AppImage, chmod +x and run. Manager by default, --couch for the couch, installer for the headless CLI.

macOS: Clarity.dmg, or Clarity-arm64.zip if you would rather not mount a disk image. Apple Silicon, built from this same commit. Open the dmg and drag Clarity Game Manager into Applications.

The macOS build is not signed, there is no Apple Developer account behind it yet, so the first launch needs one extra step. Pick whichever works on your version:

• Right-click, or Control-click, the app and choose Open, then Open again in the dialog.
• If that option never appears, double-click it, let it get blocked, then go to System Settings > Privacy & Security, scroll down, and click Open Anyway next to the message about Clarity.
• If neither shows anything, from Terminal:

xattr -dr com.apple.quarantine "/Applications/Clarity Game Manager.app"

That strips the quarantine flag macOS attaches to anything downloaded from the internet. You only need it once per install, and it is not a workaround for something broken, it is the standard cost of an app that has not been through Apple's notarization yet.