godot-platform-desktop

$npx mdskill add thedivergentai/GD-Agentic-Skills/godot-platform-desktop

Implement desktop-specific features for Windows, Linux, and macOS.

  • Provides settings menus for resolution, fullscreen, and keybind remapping.
  • Uses DisplayServer, ConfigFile, and Steam integration via Engine.has_singleton().
  • Recommends physical_keycode for rebinds and user:// for saving settings.
  • Delivers code patterns and rules for window management and input persistence.

SKILL.md

.github/skills/godot-platform-desktopView on GitHub ↗
---
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`.

---

## Godot 4.7: Desktop

- **HDR output** on Windows, macOS, and Linux (Wayland) — enable in Rendering → Viewport settings.

## 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)

0. **Resolution / stretch** — use the mini-tree below, then **MANDATORY** [desktop_window_manager.gd](scripts/desktop_window_manager.gd).
1. **Window / DPI** — **MANDATORY** [desktop_window_manager.gd](scripts/desktop_window_manager.gd): multi-monitor position, scale, mode restore.
2. **ConfigFile settings** — **MANDATORY** [desktop_settings_persistent.gd](scripts/desktop_settings_persistent.gd): graphics/audio/window under `user://`.
3. **Physical rebinds** — **MANDATORY** [physical_input_rebinder.gd](scripts/physical_input_rebinder.gd): `physical_keycode` only.
4. **Close flush** — **MANDATORY** [graceful_shutdown_handler.gd](scripts/graceful_shutdown_handler.gd): `NOTIFICATION_WM_CLOSE_REQUEST` → save → quit.
5. **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](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-export-builds/SKILL.md)).

## 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](https://docs.godotengine.org/en/stable/classes/class_displayserver.html) — Window modes, `screen_get_scale` / usable rects, and native file-dialog features behind multi-monitor and HiDPI desktop settings.
- [Multiple resolutions](https://docs.godotengine.org/en/stable/tutorials/rendering/multiple_resolutions.html) — Stretch modes, aspect, and content scale so resolution dropdowns stay sharp across 1080p–4K displays.
- [Handling quit requests](https://docs.godotengine.org/en/stable/tutorials/inputs/handling_quit_requests.html) — `NOTIFICATION_WM_CLOSE_REQUEST` / `set_auto_accept_quit(false)` so Alt+F4 and window-close flush ConfigFile before exit.
- [ConfigFile](https://docs.godotengine.org/en/stable/classes/class_configfile.html) — INI-style persistence for graphics, audio, and window state under `user://`.
- [File paths in Godot projects](https://docs.godotengine.org/en/stable/tutorials/io/data_paths.html) — Why settings and saves must use `user://` (exported `res://` is read-only).
- [InputEventKey](https://docs.godotengine.org/en/stable/classes/class_inputeventkey.html) — `physical_keycode` vs `keycode` so WASD rebinds survive AZERTY/Dvorak layouts.
- [InputMap](https://docs.godotengine.org/en/stable/classes/class_inputmap.html) — Runtime `action_erase_events` / `action_add_event` for desktop rebind UIs.
- [Using InputEvent](https://docs.godotengine.org/en/stable/tutorials/inputs/inputevent.html) — Focus-loss stuck-key pitfalls (`NOTIFICATION_APPLICATION_FOCUS_OUT`) when Alt-Tabbing on PC.
- [Window](https://docs.godotengine.org/en/stable/classes/class_window.html) — Secondary/tool windows and mode/size/position restore for true multi-window desktop apps.
- [OS](https://docs.godotengine.org/en/stable/classes/class_os.html) — `low_processor_usage_mode`, `create_process` / `execute`, and `alert` for launchers and native shell hooks.
- [Creating applications](https://docs.godotengine.org/en/stable/tutorials/ui/creating_applications.html) — Desktop-style app chrome, dialogs, and quit UX beyond game-only loops.
- [Engine](https://docs.godotengine.org/en/stable/classes/class_engine.html) — `has_singleton` / `get_singleton` guards so Steam/Epic GDExtensions never crash standalone builds.

### Related Skills

#### Prerequisites
- [godot-project-foundations](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-project-foundations/SKILL.md) — Display stretch, feature tags (`windows`/`linux`/`macos`), and project defaults every desktop settings menu depends on.
- [godot-input-handling](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-input-handling/SKILL.md) — InputEvent buffering and action design before wiring `physical_keycode` rebind UIs.
- [godot-ui-containers](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-ui-containers/SKILL.md) — Settings screens, dropdowns, and remapper rows that stay layout-correct across resolutions.

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

#### Downstream / consumers
- [godot-export-builds](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-export-builds/SKILL.md) — Windows/Linux/macOS export presets, icons, and store packaging once desktop settings and SDK wrappers are stable.
- [godot-platform-mobile](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-platform-mobile/SKILL.md) — Sibling platform skill for dual-target projects that must not assume desktop quit/window APIs on phones.
- [godot-platform-web](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-platform-web/SKILL.md) — Browser constraints (no multi-window / limited shell) when shipping the same settings stack to HTML5.

#### Master
- [godot-master](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-master/SKILL.md) — Library router and mirrored module entry for discovering this platform skill beside sibling domains.

More from thedivergentai/GD-Agentic-Skills

SkillDescription
godot-2d-animationExpert patterns for 2D animation in Godot using AnimatedSprite2D and skeletal cutout rigs. Use when implementing sprite frame animations, procedural animation (squash/stretch), cutout bone hierarchies, or frame-perfect timing systems. Trigger keywords: AnimatedSprite2D, SpriteFrames, animation_finished, animation_looped, frame_changed, frame_progress, set_frame_and_progress, cutout animation, skeletal 2D, Bone2D, procedural animation, animation state machine, advance(0).
godot-2d-physicsExpert patterns for Godot 2D physics including collision layers/masks, Area2D triggers, raycasting, and PhysicsDirectSpaceState2D queries. Use when implementing collision detection, trigger zones, line-of-sight systems, or manual physics queries. Trigger keywords: CollisionShape2D, CollisionPolygon2D, collision_layer, collision_mask, set_collision_layer_value, set_collision_mask_value, Area2D, body_entered, body_exited, RayCast2D, force_raycast_update, PhysicsPointQueryParameters2D, PhysicsShapeQueryParameters2D, direct_space_state, move_and_collide, move_and_slide.
godot-3d-lightingExpert patterns for Godot 3D lighting including DirectionalLight3D shadow cascades, OmniLight3D attenuation, SpotLight3D projectors, VoxelGI vs SDFGI, and LightmapGI baking. Use when implementing realistic 3D lighting, shadow optimization, global illumination, or light probes. Trigger keywords: DirectionalLight3D, OmniLight3D, SpotLight3D, shadow_enabled, directional_shadow_mode, directional_shadow_split, omni_range, omni_attenuation, spot_range, spot_angle, VoxelGI, SDFGI, LightmapGI, ReflectionProbe, Environment, WorldEnvironment.
godot-3d-materialsExpert patterns for Godot 3D PBR materials using StandardMaterial3D including albedo, metallic/roughness workflows, normal maps, ORM texture packing, transparency modes, and shader conversion. Use when creating realistic 3D surfaces, PBR workflows, or material optimization. Trigger keywords: StandardMaterial3D, BaseMaterial3D, albedo_texture, metallic, metallic_texture, roughness, roughness_texture, normal_texture, normal_enabled, orm_texture, transparency, alpha_scissor, alpha_hash, cull_mode, ShaderMaterial, shader parameters.
godot-3d-world-buildingExpert patterns for 3D level design using GridMap with MeshLibrary, CSG constructive solid geometry, occlusion, and runtime GridMap builders. Use when building 3D levels, modular tilesets, or BSP-style geometry. For sky/fog/Environment recipes, route to godot-3d-lighting. Trigger keywords: GridMap, MeshLibrary, set_cell_item, get_cell_item, map_to_local, local_to_map, CSGCombiner3D, CSGBox3D, CSGSphere3D, CSGPolygon3D, OccluderInstance3D, bake CSG.
godot-ability-systemExpert patterns for RPG/action ability systems including cooldown strategies, combo systems, ability chaining, skill trees with prerequisites, upgrade paths, and resource management. Use when implementing unlockable abilities, character progression, or complex skill systems. Trigger keywords: PlayerAbility, AbilityManager, cooldown, SkillTree, SkillNode, prerequisites, can_use, execute, ComboSystem, ability_chain, global_cooldown, charge_system, upgrade_path.
godot-adapt-2d-to-3dExpert patterns for migrating 2D games to 3D including node type conversions, camera systems (third-person, first-person, orbit), physics layer migration, sprite-to-model art pipeline, and control scheme adaptations. Use when porting 2D projects to 3D or adding 3D elements. Trigger keywords: CharacterBody2D to CharacterBody3D, Area2D to Area3D, Camera2D to Camera3D, Vector2 to Vector3, collision_layer migration, sprite to MeshInstance3D, 2D to 3D conversion.
godot-adapt-3d-to-2dExpert patterns for simplifying 3D games to 2D including dimension reduction strategies, 2.5D fake-depth, isometric ports, camera flattening, physics conversion, 3D-to-sprite art pipeline, and control simplification. Use when porting 3D to 2D, building 2.5D / isometric / fake-depth gameplay, creating 2D versions for mobile, or prototyping. Trigger keywords: CharacterBody3D to CharacterBody2D, Camera3D to Camera2D, Vector3 to Vector2, flatten Z-axis, 2.5D, isometric, fake depth, Y-sort, simulated Z, orthogonal projection, 3D to sprite conversion, performance optimization.
godot-adapt-desktop-to-mobileExpert patterns for porting desktop games to mobile including touch control schemes (virtual joystick, gesture detection), UI scaling for small screens, performance optimization for mobile GPUs, battery life management, and platform-specific features. Use when creating mobile ports or cross-platform mobile builds. Trigger keywords: TouchScreenButton, virtual_joystick, gesture_detector, InputEventScreenTouch, InputEventScreenDrag, mobile_optimization, battery_saving, adaptive_performance, MOBILE_ENABLED.
godot-adapt-mobile-to-desktopExpert patterns for scaling mobile games to desktop including mouse/keyboard controls, increased resolution and graphical fidelity, expanded UI layouts, settings menus, window management, and platform-specific features. Use when creating desktop ports or cross-platform releases. Trigger keywords: mouse_controls, keyboard_shortcuts, resolution_scaling, graphics_settings, fullscreen_toggle, window_modes, Steam_integration, desktop_optimization.