godot-adapt-mobile-to-desktop

绝对不要做

• 绝对不要保留仅支持触控的控件——添加鼠标／键盘替代操作。桌面设备上的触控操作体验别扭，也会降低精确度。
• 绝对不要锁定移动端分辨率——桌面设备可处理 1920x1080+ 分辨率和更高帧率。放大 UI，增加渲染距离。
• 绝对不要隐藏画质设置——桌面玩家期待可以调整画质选项（分辨率、VSync、阴影、抗锯齿）。
• 绝对不要使用移动端尺寸的 UI——触控目标（44pt）对于鼠标来说太大。将按钮／文本尺寸缩小 30-50%。
• 绝对不要忽略窗口管理——玩家期待支持全屏、无边框、最大化和多显示器。

---

可用脚本

必须：在实现相应模式前，先阅读适用的脚本。

desktop_input_adapter.gd

输入重映射前必须先阅读——将移动端操作桥接到键盘／鼠标，无需重写游戏玩法。需要 FPS 捕获时会发出 mouse_look_bridge_requested——请搭配 mouse_capture_look 使用。

hover_bridge.gd

UI 需要悬停时必须使用——补回移动端没有的桌面悬停／焦点交互提示。优先使用此脚本，而不是临时堆砌 mouse_entered。

mouse_capture_look.gd

通过 InputEventMouseMotion.relative 捕获视角移动——当仅使用适配器不够时，用于 FPS／环绕视角。

dynamic_window_manager.gd

必须使用——通过 DisplayServer 管理窗口模式／独占全屏／无边框。

keybinding_remapper.gd

运行时重映射 InputMap，并通过 ConfigFile 持久化。

cursor_state_manager.gd

管理硬件光标的显示／隐藏，以及战斗与菜单状态。

uncapped_framerate.gd

解除 VSync／Engine.max_fps 限制，支持 144Hz+。

resolution_dropdown.gd

使用 DisplayServer.screen_get_size 创建原生分辨率 OptionButton。

desktop_ui_scaler.gd

必须使用——缩小适合拇指操作的移动端控件，以适应鼠标操作密度。

scroll_wheel_zoom.gd

使用鼠标滚轮缩放替代双指捏合。

quit_confirmation.gd

必须使用——set_auto_accept_quit(false) + 通过 WM 关闭窗口时显示保存提示。

multi_monitor_handling.gd

在光标所在的屏幕上启动／放置窗口。

---

决策树——输入脚本选择

需求	使用
将触控操作映射为 WASD／鼠标，无需重写移动逻辑	desktop_input_adapter
按钮／Control 悬停样式和工具提示	hover_bridge
捕获鼠标视角（FPS／第三人称环绕）	mouse_capture_look——瞄准／视角需要捕获相对移动时必须使用；适配器的 get_aim_vector() 单独使用仅适用于俯视视角
可重新绑定按键	keybinding_remapper
将双指捏合缩放替换为滚轮缩放	scroll_wheel_zoom

当 desktop_input_adapter 发出 mouse_look_bridge_requested 时，请在玩家／摄像机支架上附加或启用 mouse_capture_look.gd——不要只注入 InputMap 就停下。

移植步骤（按顺序）

1. 必须使用 desktop_input_adapter（UI 还需搭配 hover_bridge），让每项触控操作都有精确的替代方式。
2. 使用 desktop_ui_scaler + 扩展布局（快捷栏／聊天／小地图）——布局结构使用 godot-ui-containers。
3. 使用 dynamic_window_manager + multi_monitor_handling + quit_confirmation。
4. 使用 resolution_dropdown + uncapped_framerate + 画质梯度设置（持久化到 ConfigFile）。
5. 更深入的 OS 集成 → godot-platform-desktop。

平台服务决策树（Steam / Discord）

目标	决策
在 Steam 上发布并支持云存档/成就	添加 GDExtension 桥接（例如 GodotSteam）；将初始化放在 OS.has_feature("steam") 判断之后，或使用编辑器安全的存根。不要把虚假的 Steam.* 教程代码粘贴到游戏脚本中。
仅需 Discord Rich Presence	优先使用轻量的 GDExtension/插件；在场景切换时通过 Autoload 更新状态 — 绝不要让 _ready 等待网络。
本里程碑不接入商店	删除 — 完全省略 Steam/Discord 代码路径；记录为未来的 GDExtension 探索任务。

深入方案

必须：若要超出有序步骤进行移植，请阅读 desktop-port-deep.md。首次进行键盘/鼠标重映射时不要加载此文件。

测试（发布前）

必须：在宣布移植完成前，运行 desktop-port-testing-checklist.md。不要内联部分检查清单 — 请使用参考文件。

专家技巧（简要）

• 在主资源包加载前，可通过 OS.create_process + user://settings.cfg 实现轻量启动器。
• 进行简短的 FPS 基准测试 → 写入 user://override.cfg 质量建议。
• 图形质量等级（MSAA、阴影图集、后期特效）和 UI 密度表位于 desktop-port-deep.md — 当移植流程中的条目不足以解决问题时再打开。

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接； 将相关技能用于把工作分派到相邻领域 — 不要预加载整个技能网络。

官方文档

• 使用 InputEvent — 事件处理流程：在桌面端用鼠标移动、按键和键盘操作替代 InputEventScreenTouch/ScreenDrag。
• 鼠标和输入坐标 — 了解视口与画布变换，确保鼠标瞄准和悬停命中与原触摸目标位于相同的 UI/游戏空间。
• 自定义鼠标光标 — 战斗与菜单中的硬件光标形状及显示/隐藏规则（Input.set_custom_mouse_cursor）。
• 输入示例 — 实用的 WASD、鼠标视角和操作模式，可映射到移动端虚拟摇杆/按键操作。
• 处理退出请求 — 使用 NOTIFICATION_WM_CLOSE_REQUEST / set_auto_accept_quit(false)，让操作系统的关闭按钮可以提示保存，而不是直接退出。
• 多种分辨率 — 从固定的移动端基准分辨率切换到 1080p–4K 和超宽屏时，设置拉伸模式、宽高比和内容缩放。
• DisplayServer — 全屏和多显示器移植所需的窗口模式、垂直同步、屏幕数量/尺寸/位置及刷新率查询。
• Window — 用于切换无边框/独占全屏的单窗口尺寸、位置和模式 API。
• InputMap — 在运行时将操作重新映射到键码，让 PC 玩家可以重新绑定移动端硬编码为触摸区域的操作。
• 尺寸和锚点 — 缩小拇指大小的控件以适应鼠标操作密度时，遵循锚点/偏移规则，避免破坏布局。
• 使用容器 — Box/Grid/Margin 布局规则，适用于扩展的桌面 HUD（快捷栏、聊天、迷你地图）和紧凑的移动端布局。
• 功能标签 — 使用 pc / mobile / 操作系统标签区分输入、UI 缩放和画质，无需创建单独的项目。

相关技能

前置条件

• godot-input-handling — 在为移动端操作注入 WASD/鼠标等效操作之前，共享 InputEvent 缓冲、操作映射和设备检测。
• godot-ui-containers — 设置锚点、容器和最小尺寸，确保桌面 UI 缩放调整后在不同分辨率下布局正确。
• godot-platform-mobile — 在桌面端窗口/输入路径接管之前，梳理将要替换的移动端生命周期、触摸和安全区域假设。

配套

• godot-platform-desktop — 在移动端→桌面端的控制和设置重映射到位后，深入了解 Windows/macOS/Linux DisplayServer 和操作系统集成。
• godot-camera-systems — 用于替代滑动/捏合相机控制的鼠标视角、环绕和滚轮缩放装置。
• godot-performance-optimization — 在为桌面 GPU 解锁 FPS、MSAA、阴影和绘制距离时进行性能分析并制定画质阶梯。
• godot-save-load-systems — 持久化存档管理，并与窗口关闭确认和设置 ConfigFile 持久化相连。
• godot-ui-theming — 移动端从未呈现、但桌面玩家对按钮/菜单有所期待的主题类型变体和悬停样式。
• godot-project-foundations — 每个桌面移植分支都依赖的显示拉伸、渲染器和功能标签项目默认设置。
• godot-autoload-architecture — 用于窗口管理器、输入适配器和必须跨场景切换存续的图形设置的单例归属方案。

下游 / 使用方

• godot-export-builds — 在桌面端通过输入/UI/窗口检查后，为 Windows/macOS/Linux 配置打包和 CI 导出预设。
• godot-adapt-desktop-to-mobile — 当同一代码库在桌面优先的适配后必须保留或恢复触控优先路径时使用的反向适配方案。
• godot-monte-carlo-balancer — 当鼠标精度和更高 FPS 导致移动端触控时序及瞄准曲线失效时，重新调整难度。

主入口

• godot-master — 库路由器和镜像模块入口，用于在相邻领域中发现此适配技能。