godot-platform-desktop

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](scripts/desktop_window_manager.gd)

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

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

Production settings persistence using ConfigFile for persistent INI data.

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

Expert positional rebind system using physical_keycode for AZERTY/Dvorak.

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

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

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

Expert native OS file dialogs and system alerts logic.

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

True multi-window management for secondary Viewports/Windows.

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

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

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

Eco mode optimization for desktop tools and launchers.

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

OS-level hardware detection for dynamic graphics presets.

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

Expert native shell command execution and output capture.

---

Desktop Golden Path (MANDATORY scripts)

1. Resolution / stretch — use the mini-tree below, then MANDATORY [desktop_window_manager.gd](scripts/desktop_window_manager.gd).
2. Window / DPI — MANDATORY [desktop_window_manager.gd](scripts/desktop_window_manager.gd): multi-monitor position, scale, mode restore.
3. ConfigFile settings — MANDATORY [desktop_settings_persistent.gd](scripts/desktop_settings_persistent.gd): graphics/audio/window under user://.
4. Physical rebinds — MANDATORY [physical_input_rebinder.gd](scripts/physical_input_rebinder.gd): physical_keycode only.
5. Close flush — MANDATORY [graceful_shutdown_handler.gd](scripts/graceful_shutdown_handler.gd): NOTIFICATION_WM_CLOSE_REQUEST → save → quit.
6. Store SDK — MANDATORY [platform_sdk_wrapper.gd](scripts/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](scripts/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](scripts/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](scripts/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](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, 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.