Oma-Play

🕹️ Play fun games in between intense work hours. Helps with relaxation and clearing mental fog.

A decompression arcade for software developers — instant, zero-dependency games that live in your Omarchy status bar. Click the bar icon, play for two minutes, close it, get back to work. No windows, no launchers, no waiting.

Genres inside: Snow Run (8-level text-free platformer, springs/ice/moving platforms), racer (OutRun 3D), endless runner (Chrome Dino), snake, breakout (brick-breaker), asteroids (vector shooter), wandering wraith (cave flight) and sandbox simulation (Falling Sand). All games are native QML + pure JavaScript — idle-safe (exit on close, Dino/SnowRun pausable), no web ports, no emulators, no external processes.

<span style="color: #888888;">📖 Read the Full Engineering & Architecture Documentation →</span>

📦 Install

Repo vs Plugin vs Folder — no confusion:

• GitHub repo name: omarchy-racer (https://github.com/oppenheimer-rick/omarchy-racer) — legacy name, do not rename on GitHub unless you create a new repo.
• Plugin name/id inside: Oma-Play (io.github.oppenheimer-rick.oma-play in manifest.json).
• Local folder after clone: you may keep it as Oma-play (/home/dex/bug_hunt/Oma-play) — the name on disk does not matter, the id inside manifest.json does.

One-line install — this is the ONLY working command (tested):

omarchy plugin add https://github.com/oppenheimer-rick/omarchy-racer.git --enable

Omarchy clones omarchy-racer, validates manifest.json (id: io.github.oppenheimer-rick.oma-play) and enables Oma-Play instantly. There is no https://github.com/oppenheimer-rick/oma-play.git — that URL 404s.

Manual clone + validate (exactly as the marketplace does):

git clone https://github.com/oppenheimer-rick/omarchy-racer.git Oma-play
cd Oma-play
omarchy plugin validate   # or: omarchy plugin validate .
# alternative marketplace helpers:
# omarchy plugin clone https://github.com/oppenheimer-rick/omarchy-racer.git
# omarchy plugin validate ./omarchy-racer  # path must match cloned dir

Manual enable / disable (after install):

omarchy plugin enable io.github.oppenheimer-rick.oma-play
omarchy plugin disable io.github.oppenheimer-rick.oma-play
omarchy plugin list | grep oma-play

🗑️ Removal

Safe removal — does not overwrite user configuration:

omarchy plugin disable io.github.oppenheimer-rick.oma-play
omarchy plugin remove io.github.oppenheimer-rick.oma-play

No user shell.json keys are overwritten without explicit consent.

🧘 Philosophy: The Decompression Arcade

Deep work is a muscle, and recovery is part of the training. Oma-Play is designed around the shortest possible path from "I need a break" to "I'm playing."

• Zero latency — native QML games are pure JavaScript; the panel opens instantly.
• Zero dependencies — native games are pure QML + vanilla JS; web ports run from a tiny local static server spawned on demand. No Python, no WASM runtime.
• Zero flicker, unified window — all games share the same card ratio (420×340 logical, streamed at 840×680 @60fps). Native and web no longer jump between 16:9 and 4:3 — one window, one aspect, one smooth Image buffer.
• Zero clutter — Tab cycles instant games, L opens the full library. ESC closes. F11 toggles fullscreen.

🕹️ Included Games & Toys

Native — instant play, cycle with Tab / G

Library — press L to open the Arcade Library (see Controls below)

Every title in the library is a native QML game — instant play, zero dependencies:

Web games removed: All bundled web ports (HexGL, Pac-Man, Hextris, 2048, Mario, Floppy Bird, DOOM, console-ROM emulation via EmulatorJS, …) were removed by maintainer decision. The plugin is now 100% native QML — it spawns no servers, browsers or external processes. The racer is the default game on panel open.

🎮 Controls — Complete Guide

🔄 Global (always available)

📚 Library Menu — How to Open & Use

1. Open: With the Oma-Play panel open (click Oma-Play icon in bar), press L. The CRT-styled ▓▒░ ARCADE LIBRARY ░▒▓ overlay covers the game canvas.
2. Browse: ↑ / ↓ or j / k move the yellow ▶ highlight. Enter / Space launches the highlighted title.
3. Search: Press / to focus the search box, type (e.g., snow, break), live-filter narrows the list. Enter launches the top hit. Esc clears focus back to the list.
4. Launch behaviour: Native (QML badge) — instantly swaps currentGame. No servers or browsers are ever spawned.
5. Close library: Press L again or Esc (if not typing). Mouse click on a row also launches.
6. Counts: Header shows e.g., 7 GAMES ▸ L=CLOSE (7 natives).

🕹️ Per-Game Keys (while NOT in library)

Tip: Tab while L library is closed cycles only QML natives — fastest decompression.

🔧 Technical

All games are native QML Canvas + pure JavaScript models running inside the quickshell panel — no Chromium, no local HTTP server, no external processes of any kind.

The legacy web-port tooling (games/, WebEmbedView.qml, scripts/web-stream.js, EmulatorJS player) was removed by maintainer decision; earlier native QML games remain archived in _later_work/ for isolated iteration:

cp _later_work/qml_games/*.qml .
cp _later_work/qml_games/*.js .

⚙️ Configuration

In ~/.config/omarchy/shell.json:

"right": [
  { "id": "io.github.oppenheimer-rick.oma-play" }
]

📄 Publish Your Plugin — Marketplace Checklist

This repository is ready for Omarchy Plugin Marketplace submission:

1. Prepare the repository

   • Public GitHub repository
   • Valid manifest.json in repository root (omarchy plugin validate passes)
   • README.md with install & removal instructions
   • LICENSE (MIT) and preview (preview.png)
   • Safe install and removal (no config overwrite)

2. Add a manifest — manifest.json:

   {
     "schemaVersion": 1,
     "id": "io.github.oppenheimer-rick.oma-play",
     "name": "Oma-Play",
     "version": "1.1.0",
       "description": "Play fun games in between intense work hours. Helps with relaxation and clearing mental fog — Snow Run (8-level text-free), racer, endless runner, snake, breakout, asteroids, wandering wraith and sandbox simulation, all in your Omarchy bar. Idle-safe."
   }
   

   Validate: omarchy plugin validate (inside the cloned dir) — not oma-play.git.

3. Submit — open the issue form with repository URL, category Games, tags (e.g., games, arcade, fun).

Note: Marketplace validates listings, not plugin security. Plugins run unsandboxed — you remain responsible for code, assets, documentation and license.

🛡️ Security Notice

Third-party unsandboxed code. Automated checks are limited and are not a security audit. Verify the current commit matches the reviewed commit, inspect source and capabilities, and report suspicious plugins ASAP.

📄 License

MIT License © 2026 oppenheimer-rick — see LICENSE.

🙏 Credits

• Jake Gordon — javascript-racer, javascript-snakes, javascript-breakout (MIT)
• Kenney.nl — Pixel Platformer art (CC0)