godot-platform-desktop

name	godot-platform-desktop
description	Expert blueprint for desktop platforms (Windows/Linux/macOS) covering keyboard/mouse controls, settings menus, window management (fullscreen, resolution), keybind remapping, and Steam integration. Use when targeting PC platforms or implementing desktop-specific features. Keywords desktop, Windows, Linux, macOS, settings, keybinds, ConfigFile, DisplayServer, Steam, fullscreen.

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.screen_get_scale() / usable rects.
• NEVER skip a borderless window option — Offer WINDOW_MODE_FULLSCREEN (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 NOTIFICATION_WM_CLOSE_REQUEST — Flush ConfigFile before get_tree().quit().

Performance & Integration

• NEVER run utility tools at max framerate — Enable OS.low_processor_usage_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.

desktop_window_manager.gd

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

desktop_settings_persistent.gd

Production settings persistence using ConfigFile for persistent INI data.

physical_input_rebinder.gd

Expert positional rebind system using physical_keycode for AZERTY/Dvorak.

platform_sdk_wrapper.gd

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

native_dialog_helper.gd

Expert native OS file dialogs and system alerts logic.

secondary_window_spawner.gd

True multi-window management for secondary Viewports/Windows.

graceful_shutdown_handler.gd

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

low_processor_eco_mode.gd

Eco mode optimization for desktop tools and launchers.

desktop_performance_monitor.gd

OS-level hardware detection for dynamic graphics presets.

native_shell_executor.gd

Expert native shell command execution and output capture.

---

Desktop Golden Path (MANDATORY scripts)

0. Resolution / stretch — use the mini-tree below, then MANDATORY desktop_window_manager.gd.
1. Window / DPI — MANDATORY desktop_window_manager.gd: multi-monitor position, scale, mode restore.
2. ConfigFile settings — MANDATORY desktop_settings_persistent.gd: graphics/audio/window under user://.
3. Physical rebinds — MANDATORY physical_input_rebinder.gd: physical_keycode only.
4. Close flush — MANDATORY graceful_shutdown_handler.gd: NOTIFICATION_WM_CLOSE_REQUEST → save → quit.
5. Store SDK — MANDATORY platform_sdk_wrapper.gd before any store call: if Engine.has_singleton("Steam") → Steam API; elif Engine.has_singleton("EOS") → Epic; else no-op stub. Gate features with export feature tags (steam / epic).

Resolution / stretch mini-tree

Player need	Window mode	Script hook
Fullscreen game, alt-tab friendly	WINDOW_MODE_FULLSCREEN (borderless)	desktop_window_manager.gd
Exclusive fullscreen (lowest latency)	WINDOW_MODE_EXCLUSIVE_FULLSCREEN	Same — persist choice in ConfigFile
Windowed / multi-monitor drag	WINDOW_MODE_WINDOWED + usable rect / DPI scale	Same + desktop_settings_persistent.gd

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 NOTIFICATION_APPLICATION_FOCUS_OUT, pause and Input.action_release held movement actions so OS-swallowed key-ups do not strand velocity.

2. Desktop launcher note

Lightweight launcher projects may OS.create_process the main pack after writing user://settings.cfg; pair with low_processor_eco_mode.gd while idle in menus.

Deep dives (on demand)

• Settings menu, rebind, Steam, alt-tab guard, launcher → 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, screen_get_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 — NOTIFICATION_WM_CLOSE_REQUEST / set_auto_accept_quit(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 — physical_keycode vs keycode so WASD rebinds survive AZERTY/Dvorak layouts.
• InputMap — Runtime action_erase_events / action_add_event for desktop rebind UIs.
• Using InputEvent — Focus-loss stuck-key pitfalls (NOTIFICATION_APPLICATION_FOCUS_OUT) when Alt-Tabbing on PC.
• Window — Secondary/tool windows and mode/size/position restore for true multi-window desktop apps.
• OS — low_processor_usage_mode, 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 — has_singleton / 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.