Platform: Desktop

Settings flexibility, window management, and kb/mouse precision define desktop gaming.

NEVER Do (Expert Desktop Rules)

Window & Display

• NEVER hardcode resolution or fullscreen modes — Always provide a settings menu with resolution + mode toggle.
• NEVER ignore DPI scale factors — Use DisplayServer.screengetscale() / usable rects.
• NEVER skip a borderless window option — Offer WINDOWMODEFULLSCREEN (borderless) for multi-monitor focus.

Input & Persistence

• NEVER use keycode for movement rebinds — Use physical_keycode for AZERTY/Dvorak.
• NEVER save settings or user data to res:// — Always user://.
• NEVER skip NOTIFICATIONWMCLOSEREQUEST — Flush ConfigFile before gettree().quit().

Performance & Integration

• NEVER run utility tools at max framerate — Enable OS.lowprocessorusage_mode for static tools.
• NEVER call proprietary SDKs (Steam/Epic) directly — Wrap with Engine.has_singleton() guards.
• NEVER block the main thread with massive I/O — Offload to WorkerThreadPool.

Available Scripts

MANDATORY: Read the appropriate script before implementing the corresponding pattern. Do not paste inline settings/rebind/Steam tutorials — the scripts are the golden path.

[desktopwindowmanager.gd](scripts/desktopwindowmanager.gd)

Expert DPI-aware multi-monitor window positioning using DisplayServer.

[desktopsettingspersistent.gd](scripts/desktopsettingspersistent.gd)

Production settings persistence using ConfigFile for persistent INI data.

[physicalinputrebinder.gd](scripts/physicalinputrebinder.gd)

Expert positional rebind system using physical_keycode for AZERTY/Dvorak.

[platformsdkwrapper.gd](scripts/platformsdkwrapper.gd)

Safe PC SDK singleton wrapper (Steamworks/Epic) with crash guards.

[nativedialoghelper.gd](scripts/nativedialoghelper.gd)

Expert native OS file dialogs and system alerts logic.

[secondarywindowspawner.gd](scripts/secondarywindowspawner.gd)

True multi-window management for secondary Viewports/Windows.

[gracefulshutdownhandler.gd](scripts/gracefulshutdownhandler.gd)

Safe close-request interceptor for data flushing and exit guards.

[lowprocessorecomode.gd](scripts/lowprocessorecomode.gd)

Eco mode optimization for desktop tools and launchers.

[desktopperformancemonitor.gd](scripts/desktopperformancemonitor.gd)

OS-level hardware detection for dynamic graphics presets.

[nativeshellexecutor.gd](scripts/nativeshellexecutor.gd)

Expert native shell command execution and output capture.

Desktop Golden Path (MANDATORY scripts)

1. Resolution / stretch — use the mini-tree below, then MANDATORY [desktopwindowmanager.gd](scripts/desktopwindowmanager.gd).
2. Window / DPI — MANDATORY [desktopwindowmanager.gd](scripts/desktopwindowmanager.gd): multi-monitor position, scale, mode restore.
3. ConfigFile settings — MANDATORY [desktopsettingspersistent.gd](scripts/desktopsettingspersistent.gd): graphics/audio/window under user://.
4. Physical rebinds — MANDATORY [physicalinputrebinder.gd](scripts/physicalinputrebinder.gd): physical_keycode only.
5. Close flush — MANDATORY [gracefulshutdownhandler.gd](scripts/gracefulshutdownhandler.gd): NOTIFICATIONWMCLOSE_REQUEST → save → quit.
6. Store SDK — MANDATORY [platformsdkwrapper.gd](scripts/platformsdkwrapper.gd) before any store call: if Engine.hassingleton("Steam") → Steam API; elif Engine.hassingleton("EOS") → Epic; else no-op stub. Gate features with export feature tags (steam / epic).

Resolution / stretch mini-tree

CI smoke: headless --path . --quit-after 1 with settings round-trip write/read under user:// before merge (pairs with godot-export-builds).

Expert Callouts (keep short — not full tutorials)

1. Alt-Tab stuck-input guard

On NOTIFICATIONAPPLICATIONFOCUSOUT, pause and Input.actionrelease held movement actions so OS-swallowed key-ups do not strand velocity.

2. Desktop launcher note

Lightweight launcher projects may OS.createprocess the main pack after writing user://settings.cfg; pair with [lowprocessorecomode.gd](scripts/lowprocessoreco_mode.gd) while idle in menus.

Deep dives (on demand)

• Settings menu, rebind, Steam, alt-tab guard, launcher → [desktop-expert-patterns.md](references/desktop-expert-patterns.md)

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API;
load Related Skills when routing work to a peer domain — do not preload the whole lattice.

Official Documentation

• DisplayServer — Window modes, screenget_scale / usable rects, and native file-dialog features behind multi-monitor and HiDPI desktop settings.
• Multiple resolutions — Stretch modes, aspect, and content scale so resolution dropdowns stay sharp across 1080p–4K displays.
• Handling quit requests — NOTIFICATIONWMCLOSEREQUEST / setautoacceptquit(false) so Alt+F4 and window-close flush ConfigFile before exit.
• ConfigFile — INI-style persistence for graphics, audio, and window state under user://.
• File paths in Godot projects — Why settings and saves must use user:// (exported res:// is read-only).
• InputEventKey — physicalkeycode vs keycode so WASD rebinds survive AZERTY/Dvorak layouts.
• InputMap — Runtime actioneraseevents / actionadd_event for desktop rebind UIs.
• Using InputEvent — Focus-loss stuck-key pitfalls (NOTIFICATIONAPPLICATIONFOCUS_OUT) when Alt-Tabbing on PC.
• Window — Secondary/tool windows and mode/size/position restore for true multi-window desktop apps.
• OS — lowprocessorusagemode, create_process / execute, and alert for launchers and native shell hooks.
• Creating applications — Desktop-style app chrome, dialogs, and quit UX beyond game-only loops.
• Engine — hassingleton / get_singleton guards so Steam/Epic GDExtensions never crash standalone builds.

Related Skills

Prerequisites

• godot-project-foundations — Display stretch, feature tags (windows/linux/macos), and project defaults every desktop settings menu depends on.
• godot-input-handling — InputEvent buffering and action design before wiring physical_keycode rebind UIs.
• godot-ui-containers — Settings screens, dropdowns, and remapper rows that stay layout-correct across resolutions.

Complements

• godot-save-load-systems — Game-save ownership that pairs with ConfigFile settings and graceful close-request flushes.
• godot-autoload-architecture — Singleton homes for window managers, SDK wrappers, and shutdown handlers.
• godot-audio-systems — Bus volume persistence that desktop graphics/audio options menus usually expose together.
• godot-adapt-desktop-to-mobile — Touch/safe-area remaps when the same project keeps desktop kb/mouse paths after a mobile port.
• godot-adapt-mobile-to-desktop — Bringing touch-first titles up to window modes, keybinds, and multi-monitor expectations.
• godot-composition-apps — Tooling/launcher composition patterns that lean on eco mode, native dialogs, and secondary windows.
• godot-performance-optimization — Profiling and quality presets after OS-level hardware detection suggests Ultra vs Balanced.

Downstream / consumers

• godot-export-builds — Windows/Linux/macOS export presets, icons, and store packaging once desktop settings and SDK wrappers are stable.
• godot-platform-mobile — Sibling platform skill for dual-target projects that must not assume desktop quit/window APIs on phones.
• godot-platform-web — Browser constraints (no multi-window / limited shell) when shipping the same settings stack to HTML5.

Master

• godot-master — Library router and mirrored module entry for discovering this platform skill beside sibling domains.