Skip to content

Getting Started

Jump to bottom
P3DROVFX edited this page Oct 12, 2026 · 2 revisions

Getting Started

New to ii-p3drovfx? This page takes you from a fresh clone to a comfortable desktop — installation, the first ten minutes, and where to go next.

Before you install

Two hard requirements:

  • Hyprland 0.56.1 or newer — the config uses Hyprland's native Lua system.
  • Matugen 4.1.0 or newer — for wallpaper color generation (Matugen 3 mostly works, but 4.1+ is the supported version; on Fedora the installer enables a COPR that provides it).

ii-p3drovfx sits on top of the illogical-impulse base dotfiles. You don't need them pre-installed — the setup script can install them for you.

Installation

git clone https://github.com/P3DROVFX/ii-p3drovfx.git
cd ii-p3drovfx
./setup-ii-p3drovfx.sh install

install sets up the base illogical-impulse dotfiles first, then applies the ii-p3drovfx Quickshell config on top. If you already run illogical-impulse (or a fork of it), run the script bare instead — it just applies the config over what you have:

./setup-ii-p3drovfx.sh

Along the way the script asks before anything invasive: whether to overlay the fork's Hyprland config onto ~/.config/hypr, whether to keep your existing config.json, and it backs up whatever it replaces by default.

It also symlinks itself to ~/.local/bin/ii-p3drovfx, so from then on you have a small CLI:

ii-p3drovfx update    # refresh to the latest version of your current branch
ii-p3drovfx restart   # restart Quickshell
ii-p3drovfx doctor    # report resolved paths, active state and tooling
ii-p3drovfx help      # the full command surface

On Arch, install ends by putting the AUR quickshell-git back in place of the base installer's pinned build — this fork is written against Quickshell master. The script asks first.

Your first ten minutes

Once the shell is up, do these in order:

  1. Set a wallpaper — press Ctrl + Super + T to open the wallpaper selector. This isn't just decoration: the entire Material You color palette is generated from your wallpaper, so the whole shell re-themes itself the moment you pick one.
  2. Open Settings — press Super + I. This is where almost everything on this wiki is toggled. Have a scroll through the sections just to see what exists.
  3. Open the Cheat Sheet — press Super + /. Its keybind list is generated live from your actual Hyprland config, so it's never out of date. This is the page to come back to whenever you forget a bind.
  4. Tap Super — that alone opens the launcher. Type an app name, a math expression (sqrt(2)*100), or a conversion (120 usd to eur) and it just works, no prefixes needed.
  5. Press Super + N — the right sidebar Dashboard: Wi-Fi, Bluetooth, audio, quick toggles, calendar and to-dos in one surface.

The keybinds you need on day one

Keys What it does
Super (tap) Launcher / search
Super + I Settings
Super + / Cheat Sheet (all keybinds, live)
Super + N Dashboard sidebar
Super + Tab Workspace overview
Super + Return Terminal
Super + Q Close window
Ctrl + Super + T Wallpaper selector

The full list lives on the Keybinds page.

Where your stuff lives

  • ~/.config/illogical-impulse/config.json — every Settings-app option persists here. Changes apply live in both directions: flip a toggle in Settings and the file updates; edit the file and the shell follows. See the Configuration Reference.
  • ~/.config/hypr/custom/ — your personal Hyprland overrides (keybinds, rules, variables). Put changes here, not in the main config files — updates overwrite those.
  • ~/.local/state/quickshell/states.json — durable user data that should survive preset changes and config resets: search aliases, Google Drive backup settings, and similar.
  • GNOME Keyring — API credentials (AI keys, Gmail and TickTick OAuth) are stored securely in the keyring, not in config files.

Turning on the big features

Everything below has a step-by-step guide on its own page — here's the one-line version of each:

  • Desktop widgets — clocks, media players, weather and more, living on your wallpaper. Enable and arrange them from Settings, drag them where you like. → Desktop Widgets
  • Bar & Dynamic Island — pick a bar layout and enable the floating island activity hub in Settings → Bar. → Bar & Dynamic Island
  • Screenshots & annotation — Super + Shift + S to snip, then right-click the selection to annotate on the spot. → Screenshot Editor
  • Screen recording — Super + Shift + R for a region, Ctrl + Alt + R for fullscreen; a trim/crop/compress editor offers itself when you stop. → Screen Capture & Recording, Video Editor
  • Phone integration — pair your Android phone over KDE Connect, then mirror apps, use it as a webcam, or browse your contacts. → Phone Integration
  • AI assistant — Super + A opens the assistant sidebar; add an API key (or point it at local Ollama) and it can even edit your shell config for you. → AI Integration
  • Calendar, To-Do & Gmail — the Dashboard's widgets can sync with TickTick and show your Gmail inbox once you connect accounts. → Sidebar Dashboard
  • Theming deep-dive — light/dark schedules, transparency, fonts, icon theming, and whole-setup presets you can export and share. → Customization

Keeping it up to date

Two equivalent paths:

  • Settings → About — the Update section shows whether your branch is behind and runs the updater for you.
  • ii-p3drovfx update in a terminal — refreshes the fork and branch you're already on.

Your config.json is kept across updates and branch hops (it's only reset when switching to a different fork, where the schema changes — and a backup is made even then).

If something breaks

  • ii-p3drovfx doctor — reports resolved paths, active state and tooling versions.
  • ./diagnose (in the repo) — generates system info for bug reports.
  • Check Known Issues — the honest list of rough edges and required extras.
  • Ctrl + Super + R restarts the shell without touching your session.

If you hit something new, open an issue in the ii-p3drovfx repository — not in the upstream projects.

Related pages

← Back to Home

Clone this wiki locally