dotfiles/docs/superpowers/specs/2026-07-15-niri-gamemode-design.md

# Niri Gamemode Design

**Date:** 2026-07-15
**Status:** Approved

## Summary

Add a compositor-level "gamemode": while a game is running, inhibit idle/blanking,
silence notifications, switch to the `performance` power profile (and bump the fan),
and hide waybar — then revert everything cleanly when the game ends. One script,
`scripts/gamemode-session.sh`, is the whole engine. It is driven by **three
independent sources** and reference-counted, so the triggers can overlap safely:

- **Window watch (`winwatch`)** — `scripts/gamemode-watch.py`, launched at niri
  startup, subscribes to niri's event stream and toggles gamemode whenever a game
  window (app_id matching `steam_app_*`, RuneLite, or gamescope) is open. This makes
  Steam games automatic with **zero per-game setup** — the primary trigger.
- **Feral (`feral`)** — Feral `gamemoded` custom start/end hooks, for
  gamemode-aware launchers run with `gamemoderun` that the window watch may not match.
- **Manual (`manual`)** — a `Mod+G` niri keybind, for anything else.

Effects apply on the first activation (0→1 active sources) and revert on the last
deactivation (1→0). Also removes three dead VRR window-rules found during review.

> **Addendum (2026-07-15):** The window-watch source was added after the initial
> design so Steam games trigger gamemode globally instead of needing
> `gamemoderun %command%` per game. See "Window watch" below.

## Current Behaviour

- **Compositor:** niri 26.04, single internal panel `eDP-1` (BOE, 2256×1504@60,
  **VRR not supported**). Config at `niri/config.kdl`.
- **Idle:** `hypridle` blanks the panel at 5 min, locks at 10 min, suspend-then-
  hibernate at 30 min. It honors idle inhibitors (`ignore_dbus_inhibit = false`,
  `ignore_systemd_inhibit = false`). A controller/turn-based game with no kbd/mouse
  input therefore goes dark at 5 minutes.
- **Notifications:** `mako`, currently with no config file (running on defaults) — so
  toasts pop over fullscreen games and there is no mode to suppress them.
- **Power:** `power-profiles-daemon` (AMD pstate); active profile read/set via
  `powerprofilesctl`, waybar module refreshed with `pkill -RTMIN+8 waybar` (and
  `-RTMIN+9`). Fan via `fw-fanctrl` with a virtual `auto` mode that maps
  profile→strategy (`performance` → `agile`) when
  `$XDG_STATE_HOME/fan-profile-auto` exists.
- **waybar:** launched directly (`spawn-at-startup "waybar"`); `waybar-restart`
  script exists.
- **Feral gamemode:** `gamemoded` installed, **no `gamemode.ini`** → no custom hooks.
- **Script convention:** `scripts/<name>.sh` is symlinked to `~/.local/bin/<name>`
  (no `.sh` in the bin name), e.g. `power-profile`, `fan-profile`, `screenshot`.

### Review findings (delivered separately, cleanup folded into this spec)

- 🔴 **Three VRR rules are dead code.** The panel doesn't support VRR, so all three
  `variable-refresh-rate true` rules are no-ops. The `match is-focused=true` one is
  also conceptually wrong (it targets every focused window, not games).
- 🟠 **Idle blanks mid-game** (the 5-min issue above) — the main problem gamemode fixes.
- 🟡 **Notifications interrupt fullscreen.**
- 🟢 `match app-id="steam_app_"` is an unanchored regex (looser than the other
  anchored rules) — noted, left as-is.

## Target Behaviour

### Sources and reference counting

State lives in a runtime dir `${XDG_RUNTIME_DIR}/gamemode/`. A "source" is either
`feral` or `manual`, represented by a marker file (`src.feral`, `src.manual`).
Gamemode is **active iff at least one source marker exists**.

```
add <source>:
  was_active = (any src.* exists)
  touch src.<source>
  if not was_active:  snapshot baseline + apply effects

del <source>:
  rm -f src.<source>
  if no src.* remain:  read baseline + revert effects, clear state dir

toggle:            # what Mod+G calls
  if src.manual exists → del manual   else → add manual

status:            # for a future waybar module; prints active|inactive, exit 0/1
```

Applying only on 0→1 and reverting only on 1→0 makes overlap safe: launch a Steam
game (feral add) *and* hit `Mod+G` (manual add), and effects apply once; effects
revert only when both are gone. Idempotent and crash-tolerant — stale markers are
harmless, and baseline is re-snapshotted only when transitioning from zero sources.

### Baseline snapshot (captured on 0→1)

Written into the state dir so revert restores exactly what was there:

- `baseline.profile` — `powerprofilesctl get` at entry.
- `baseline.waybar` — `1` if waybar was running at entry, else `0`.
- `baseline.fanauto` — `1` if `$XDG_STATE_HOME/fan-profile-auto` exists at entry.
- `idle.pid` — PID of the idle-inhibit process (written when it launches).

### Effects

| Effect | Enter | Revert |
|---|---|---|
| **Idle inhibit** | `systemd-inhibit --what=idle --who=gamemode --why="gaming session" --mode=block sleep infinity &`, record PID in `idle.pid`. hypridle honors systemd idle inhibitors, so its blank/lock/hibernate timers stop. | `kill` the recorded PID; remove `idle.pid`. |
| **Do-not-disturb** | `makoctl mode -a do-not-disturb` (requires a `[mode=do-not-disturb]` block — see mako config below). | `makoctl mode -r do-not-disturb`. |
| **Performance profile** | if `baseline.profile` != `performance`: `powerprofilesctl set performance`, then `pkill -RTMIN+8 waybar`. If `baseline.fanauto`=1: `fw-fanctrl use agile`. | restore `baseline.profile` (only if we changed it), `pkill -RTMIN+8 waybar`; if `baseline.fanauto`=1 remap fan to match the restored profile (`fan-profile`'s existing auto poll also reconciles within 5 s, so this is belt-and-suspenders). |
| **Hide waybar** | if waybar running: `pkill -x waybar`. | if `baseline.waybar`=1: relaunch `waybar` detached (`setsid waybar >/dev/null 2>&1 &`). |

All effect steps are individually guarded (`command -v`, `2>/dev/null`) so a missing
tool degrades to a no-op rather than aborting the rest — gamemode must never wedge a
session. Revert always runs every restore step regardless of individual failures.

### Failure / edge cases

- **Stale markers after a crash:** next `add` sees markers, treats itself as
  already-active, and won't re-snapshot — but a manual `gamemode-session reset`
  (clears the state dir and force-reverts) is provided as an escape hatch. `toggle`
  from a stale-active state will `del manual` and, if that empties the sources,
  revert — self-healing in the common case.
- **Idle PID already dead:** `kill` failure is ignored.
- **profile unchanged at entry** (already `performance`): we don't touch it and don't
  restore it, so we never clobber a deliberate user choice.

## Implementation

### 1. `scripts/gamemode-session.sh` (new)

`bash`, mirrors the house style of the other scripts. Structure:

- Constants: `STATE_DIR="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/gamemode"`,
  `FAN_AUTO="${XDG_STATE_HOME:-$HOME/.local/state}/fan-profile-auto"`.
- Helpers: `is_active`, `snapshot_baseline`, `apply_effects`, `revert_effects`,
  each effect as a small function.
- Dispatch on `$1`: `add`/`del` (with `$2` = source), `toggle`, `status`, `reset`.
- Symlinked to `~/.local/bin/gamemode-session` (same as every other script; add the
  symlink line to `install.sh` if it enumerates scripts, else create it manually to
  match the existing ones).

Named `gamemode-session` (not `gamemode`) to avoid any collision with Feral's
`gamemoderun`/`gamemoded` namespace.

### 2. `mako/config` (new file in dotfiles → `~/.config/mako/config`)

mako has no config today; DND needs a mode block. Fold in the current visible
settings so nothing changes visually, then add the mode:

```ini
background-color=#1d1f21
text-color=#c5c8c6
border-size=2
border-color=#81a2be
default-timeout=4000

[mode=do-not-disturb]
invisible=1
```

`invisible=1` hides new notifications while the mode is active; removing the mode
restores normal display. (History is retained — nothing is lost, just not shown.)

### 3. `gamemode.ini` (new file in dotfiles → `~/.config/gamemode.ini`)

```ini
[custom]
start=/home/alex/.local/bin/gamemode-session add feral
end=/home/alex/.local/bin/gamemode-session del feral
```

Absolute path because gamemoded's exec environment is minimal. No other gamemode
tuning (Feral's defaults already set the CPU governor).

### 4. `niri/config.kdl` (edited)

**Add** the keybind (near the other `spawn` binds):

```
Mod+G { spawn "gamemode-session" "toggle"; }
```

**Remove** the three dead VRR rules:
- the `variable-refresh-rate true` line inside the `steam_app_` rule,
- the entire `match is-focused=true { variable-refresh-rate true }` rule.

Leave a one-line comment on the `steam_app_` rule noting to re-add
`variable-refresh-rate true` if a VRR-capable external monitor is ever attached.

### 5. `scripts/gamemode-watch.py` (new) — window watch

A Python daemon (Python already used by the theme generator) launched via
`spawn-at-startup "gamemode-watch"`. It runs `niri msg --json event-stream` and
maintains the set of open **game** windows:

- `is_game(app_id)` matches `steam_app_` (substring), the RuneLite ids
  (`net-runelite-client-RuneLite|runelite|RuneLite`), and `gamescope`
  (case-insensitive) — mirrors the niri window rules. Bolt's *launcher* window is
  deliberately excluded (it would trigger before you're in-game).
- `WindowsChanged` (connect snapshot) rebuilds the set; `WindowOpenedOrChanged`
  adds/removes by app_id; `WindowClosed` (id only) discards by id.
- On empty→non-empty it calls `gamemode-session add winwatch`; non-empty→empty,
  `del winwatch`.
- Event logic is a pure `Watcher` class (injected `emit`) so it unit-tests without
  niri or subprocesses (`scripts/tests/gamemode-watch.test.py`).
- Robustness: reconnects if the stream drops while niri is alive; a SIGTERM handler
  and a `finally` guarantee `del winwatch` on exit, so the watcher stopping can
  never leave gamemode stuck on.

## Files Touched

- `scripts/gamemode-session.sh` — **new**, the engine.
- `scripts/gamemode-watch.py` — **new**, niri-event-stream window watch (primary
  auto-trigger). Tested by `scripts/tests/gamemode-watch.test.py`.
- `mako/config` — **new**, adds the `do-not-disturb` mode (plus current settings);
  also un-ignored in `.gitignore` (was previously untracked by choice).
- `gamemode.ini` — **new**, Feral start/end hooks.
- `niri/config.kdl` — add `Mod+G` bind; `spawn-at-startup "gamemode-watch"`; remove
  3 dead VRR rules; add one comment.
- `install.sh` — link `gamemode-session`, `gamemode-watch`, `gamemode.ini`, and
  `mako/config` (the last was never linked before).

## Usage

- **Steam / RuneLite / gamescope games:** nothing to do — the window watch turns
  gamemode on when a game window opens and off when the last one closes.
- **Gamemode-aware launchers** (Lutris/Heroic via `gamemoderun`): covered by the
  Feral hooks even if their window app_id isn't matched.
- **Anything else / manual override:** `Mod+G` to toggle.
- All three converge on `gamemode-session`; overlapping is safe (reference-counted).

## Out of Scope (YAGNI)

- **gamescope wrapper / upscaling / frame limiting** — separate concern; can be
  layered into a game's launch command independently.
- **Per-game profiles** — one uniform gamemode for now.
- **waybar gamemode indicator** — the `status` subcommand is provided so a
  `custom/gamemode` module can be added later, but no module ships now.
- **Cross-machine sync of gamemode state** — state is per-boot runtime only, by design.
- **Touching VRR behaviour for external monitors** — left as a comment breadcrumb;
  no rule added until such a monitor exists.