The manual

On the desktop

OmaCRT installs a launcher, a display process and command-line tools alongside your existing desktop. It is an independent project, not a distribution or a version of Omarchy. This chapter lists the files it installs and the settings it changes.

The main changes to check are the system service, the Omarchy menu entry, a temporary Hyprland setting and files created inside game collections.

User-level installation

The ordinary install needs no privileges and puts four programs where a user's own programs go.

On Omarchy, the installer adds three desktop plugins in the third-party plugin directory:

This user-level installation adds no files under /usr, /etc or /opt. It adds no desktop entry, shell-profile line, PATH change, udev rule or policy rule. The system service and Omarchy menu entry are described below.

The bar widget includes a second copy of the omacrt binary. It calls this copy by path so that the plugin always runs the version installed with it.

Changing a plugin's files is not enough for the desktop to show the new version. Omarchy's shell keeps the QML it has already loaded, and neither a plugin rescan nor a configuration reload recompiles it. The installer restarts the shell for you. If the session is locked it stops short and says so, because a reload behind a lock screen takes the shell down with it.

System service

The separate system install marks the television connector as a non-desktop output before Hyprland starts. Writing to the kernel debug interface and re-probing the connector require root. Use this service if the connector is not already available for leasing.

The boot-time service installs these files:

The installer leaves distribution units unchanged. It adds no drop-in, uses no systemctl edit and creates no symlink in another unit’s wants directory. The new unit is a oneshot service that runs at boot and exits.

Its restrictions include ProtectSystem=strict, ProtectHome, PrivateTmp, PrivateNetwork, NoNewPrivileges, MemoryDenyWriteExecute, RestrictNamespaces and ProtectKernelModules. It has two capabilities and write access to three paths. Its stop step restores the original display identification.

The launcher, display process, command line and both plugins run as your user. The display process receives access to the connector through the lease file descriptor supplied by Hyprland.

Omarchy menu and themes

The installer adds a Television entry to this Omarchy menu extension file:

~/.config/omarchy/extensions/omarchy-menu.jsonc

The Television entry in Omarchy's own menu is rows added to that file, between two markers:

// omacrt: begin
   ...the Television rows...
// omacrt: end

Uninstall removes the block only when both markers are present. If either marker is missing, it leaves the file unchanged.

OmaCRT reads the current theme colours and the list of installed themes without modifying them. It uses Omarchy’s published commands to validate, enable, disable and list plugins, and to request a shell rescan.

Temporary Hyprland setting

While the television is on, the project sets one option in the running compositor, misc:on_focus_under_fullscreen, to zero. It reads the value first, and switching the television off puts back whatever it found.

This setting exists only in the running compositor. OmaCRT does not write it to your configuration, and it does not survive a reboot.

Data directories

OmaCRT keeps its data in four directories. Each follows the corresponding environment variable:

The emulator configuration in the first of those is the project's own file, handed to RetroArch on the command line. Your own RetroArch configuration is not edited.

What it does not touch

The installer and runtime leave the following parts of the system unchanged:

• Packages: the installer compiles OmaCRT and copies its own programs. It does not install, replace or hold packages, or edit package-owned files.
• Kernel: it builds, loads or blacklists no modules and adds no kernel parameters. The stock kernel’s interlace limitation is described in The signal.
• Desktop compositor: Hyprland remains installed and manages every output except the leased connector. OmaCRT uses its published interfaces.
• Emulators and players: RetroArch, mpv and the other programs use OmaCRT’s configuration passed on the command line.
• Login: the installer adds nothing to your session autostart. The separate system service runs at boot.
• Original game files remain unchanged. The following section lists the additional files OmaCRT can create beside them.

Files created in your collection

The launcher can create files in a collection in three cases:

• A small .scummvm file in a ScummVM game's directory, the way ScummVM identifies a game at all.
• Disc images extracted beside the archive they came from, for the same reason.
• A converted copy of a video, named after the original, when a conversion is asked for.

Nothing else in a collection is written, renamed or moved, and the scan itself only reads.

Uninstalling

The uninstall removes the four programs, both plugin directories, and the menu block. It disables the plugins through Omarchy's own command before removing them. If the session is locked it deliberately stops short of the plugins, because the shell reloads plugin code whenever those directories change, and a reload behind a lock screen takes the shell down with it.

The system half is removed separately, which disables and deletes the unit and its directory. The connector goes back to being an ordinary desktop output at the next boot.

Uninstall keeps the four data directories so that reinstalling preserves settings and the library scan. Delete those directories to remove that data. Original game files and the additional files described above remain in the collection.

Without Omarchy

OmaCRT’s television features require Hyprland. Omarchy supplies the optional desktop integration.

On a Hyprland desktop, the command line, launcher and display process support the boot-time override, lease, modelines, games, video and music.

Without the omarchy command, the diagnostic report labels desktop integration as Hyprland and skips the bar-plugin check. The bar widget, panel, library overlay and pads overlay require Omarchy’s shell. The Television entry requires its menu. The Style screen uses a built-in palette when Omarchy themes are unavailable.

Other desktops are currently unsupported. OmaCRT would need support for their connector-leasing and compositor interfaces.