godot-platform-desktop

平台：桌面

设置灵活性、窗口管理以及键盘／鼠标操控精度，是桌面游戏的关键。

绝对不要做的事（桌面端专家规则）

窗口与显示

• 绝不要硬编码分辨率或全屏模式 — 始终提供设置菜单，以便切换分辨率和显示模式。
• 绝不要忽略 DPI 缩放因子 — 使用 DisplayServer.screen_get_scale() / 可用矩形。
• 绝不要省略无边框窗口选项 — 提供 WINDOW_MODE_FULLSCREEN（无边框），便于在多显示器环境下专注于游戏。

输入与持久化

• 绝不要在移动操作的键位重绑定中使用 keycode — 使用 physical_keycode，以适配 AZERTY/Dvorak 键盘布局。
• 绝不要将设置或用户数据保存到 res:// — 始终使用 user://。
• 绝不要省略 NOTIFICATION_WM_CLOSE_REQUEST — 在调用 get_tree().quit() 前刷新 ConfigFile。

性能与集成

• 绝不要让实用工具以最高帧率运行 — 为静态工具启用 OS.low_processor_usage_mode。
• 绝不要直接调用专有 SDK（Steam/Epic） — 使用 Engine.has_singleton() 进行保护。
• 绝不要因大量 I/O 阻塞主线程 — 将其移交给 WorkerThreadPool。

---

可用脚本

强制要求：在实现对应模式前，阅读相应脚本。不要直接粘贴内联设置／键位重绑定／Steam 教程 — 这些脚本是首选实现方式。

desktop_window_manager.gd

使用 DisplayServer 实现 DPI 感知的多显示器窗口定位。

desktop_settings_persistent.gd

使用 ConfigFile 持久化 INI 数据的生产级设置方案。

physical_input_rebinder.gd

使用 physical_keycode 实现适配 AZERTY/Dvorak 键盘布局的专家级位置重绑定系统。

platform_sdk_wrapper.gd

带崩溃保护的安全 PC SDK 单例封装（Steamworks/Epic）。

native_dialog_helper.gd

专家级原生操作系统文件对话框与系统警报逻辑。

secondary_window_spawner.gd

用于次级 Viewport/Window 的真正多窗口管理。

graceful_shutdown_handler.gd

安全拦截关闭请求，以刷新数据并保护退出流程。

low_processor_eco_mode.gd

针对桌面工具和启动器的节能模式优化。

desktop_performance_monitor.gd

用于动态设置图形预设的操作系统级硬件检测。

native_shell_executor.gd

专家级原生 shell 命令执行与输出捕获。

---

桌面端首选实现路径（强制脚本）

0. 分辨率／拉伸 — 使用下方的迷你树，然后必须使用 desktop_window_manager.gd。
1. 窗口／DPI — 必须使用 desktop_window_manager.gd：多显示器定位、缩放和模式恢复。
2. ConfigFile 设置 — 必须使用 desktop_settings_persistent.gd：将图形／音频／窗口设置保存到 user://。
3. 物理按键重绑定 — 必须使用 physical_input_rebinder.gd：仅使用 physical_keycode。
4. 关闭时刷新数据 — 必须使用 graceful_shutdown_handler.gd：NOTIFICATION_WM_CLOSE_REQUEST → 保存 → 退出。
5. 商店 SDK — 进行任何商店调用前，必须使用 platform_sdk_wrapper.gd：if Engine.has_singleton("Steam") → Steam API；elif Engine.has_singleton("EOS") → Epic；否则使用空操作桩。使用导出功能标签（steam / epic）限制功能。

分辨率 / 拉伸迷你决策树

玩家需求	窗口模式	脚本钩子
全屏游戏，支持便捷地切换应用	WINDOW_MODE_FULLSCREEN（无边框）	desktop_window_manager.gd
独占全屏（延迟最低）	WINDOW_MODE_EXCLUSIVE_FULLSCREEN	同上 — 在 ConfigFile 中保存选择
窗口模式 / 拖动到多个显示器	WINDOW_MODE_WINDOWED + 可用矩形 / DPI 缩放	同上 + desktop_settings_persistent.gd

CI 冒烟测试： 合并前，在无头模式下使用 --path . --quit-after 1，在 user:// 下进行设置往返写入 / 读取测试（与 godot-export-builds 配合）。

专家提示（保持简短 — 不是完整教程）

1. Alt-Tab 输入卡住防护

收到 NOTIFICATION_APPLICATION_FOCUS_OUT 时，暂停并对已按住的移动操作调用 Input.action_release，避免操作系统拦截按键释放事件后导致速度无法归零。

2. 桌面启动器说明

轻量级启动器项目可以在写入 user://settings.cfg 后，通过 OS.create_process 启动主程序包；在菜单空闲时，可与 low_processor_eco_mode.gd 配合使用。

深入了解（按需阅读）

• 设置菜单、按键重绑定、Steam、Alt-Tab 防护、启动器 → desktop-expert-patterns.md

参考资料

渐进式披露：仅在研究特定 API 时打开官方文档链接； 将工作分配给相邻领域时再加载相关技能 — 不要预先加载整个知识体系。

官方文档

• DisplayServer — 窗口模式、screen_get_scale / 可用矩形，以及多显示器和 HiDPI 桌面设置中使用的原生文件对话框功能。
• 多种分辨率 — 拉伸模式、宽高比和内容缩放，确保分辨率下拉选项在 1080p–4K 显示器上都清晰。
• 处理退出请求 — 使用 NOTIFICATION_WM_CLOSE_REQUEST / set_auto_accept_quit(false)，确保 Alt+F4 和关闭窗口时先将 ConfigFile 写入磁盘再退出。
• ConfigFile — 在 user:// 下以 INI 风格保存图形、音频和窗口状态。
• Godot 项目中的文件路径 — 了解为何设置和存档必须使用 user://（导出后的 res:// 为只读）。
• InputEventKey — 了解 physical_keycode 与 keycode 的区别，确保 WASD 按键重绑定在 AZERTY/Dvorak 布局下仍有效。
• InputMap — 用于桌面端按键重绑定界面的运行时 action_erase_events / action_add_event。
• 使用 InputEvent — 在 PC 上使用 Alt-Tab 时，焦点丢失可能导致按键卡住（NOTIFICATION_APPLICATION_FOCUS_OUT）。
• Window — 用于真正的多窗口桌面应用的次级 / 工具窗口，以及模式 / 大小 / 位置恢复。
• OS — 启动器和原生 Shell 钩子可用的 low_processor_usage_mode、create_process / execute 和 alert。
• 创建应用程序 — 游戏循环以外的桌面风格应用外观、对话框和退出体验。
• Engine — 使用 has_singleton / get_singleton 防护，避免 Steam/Epic GDExtensions 导致独立构建崩溃。

相关技能

先决条件

• godot-project-foundations — 显示拉伸、功能标签（windows/linux/macos）以及所有桌面设置菜单都依赖的项目默认设置。
• godot-input-handling — 在连接 physical_keycode 按键重绑定界面前，了解 InputEvent 缓冲和操作设计。
• godot-ui-containers — 确保设置界面、下拉菜单和重绑定行在不同分辨率下保持正确布局。

互补技能

• godot-save-load-systems — 与 ConfigFile 设置和优雅处理关闭请求时的刷新相配合的游戏存档所有权管理。
• godot-autoload-architecture — 窗口管理器、SDK 封装器和关闭处理程序的单例归属。
• godot-audio-systems — 音频总线音量持久化，通常会与桌面图形和音频选项菜单一同呈现。
• godot-adapt-desktop-to-mobile — 当同一项目移植到移动平台后仍保留桌面键盘／鼠标路径时，进行触控／安全区域映射调整。
• godot-adapt-mobile-to-desktop — 将触控优先的作品适配到窗口模式、按键绑定和多显示器使用预期。
• godot-composition-apps — 依赖生态模式、原生对话框和次级窗口的工具／启动器组合模式。
• godot-performance-optimization — OS 级硬件检测建议采用 Ultra 还是 Balanced 后，进行性能分析和质量预设配置。

下游／使用方

• godot-export-builds — 桌面设置和 SDK 封装器稳定后，配置 Windows/Linux/macOS 导出预设、图标和商店打包。
• godot-platform-mobile — 面向双目标项目的同级平台技能；此类项目不得假定手机支持桌面退出／窗口 API。
• godot-platform-web — 将同一套设置体系部署到 HTML5 时，了解浏览器限制（不支持多窗口／shell 支持有限）。

主技能

• godot-master — 技能库路由器和镜像模块入口，用于发现此平台技能及其同级领域技能。