godot-adapt-mobile-to-desktop

NEVER Do

• NEVER keep touch-only controls — Add mouse/keyboard alternatives. Touch controls on desktop feel awkward and limit precision.
• NEVER lock to mobile resolution — Desktop can handle 1920x1080+ and higher frame rates. Upscale UI, increase render distance.
• NEVER hide graphics settings — Desktop players expect quality options (resolution, VSync, shadows, anti-aliasing).
• NEVER use mobile-sized UI — Touch targets (44pt) are too large for mouse. Reduce button/text size by 30-50%.
• NEVER forget window management — Players expect fullscreen, borderless, maximize, and multi-monitor support.

---

Available Scripts

> MANDATORY: Read the appropriate script before implementing the corresponding pattern.

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

MANDATORY first read for input remap — Bridges mobile actions to keyboard/mouse without rewriting gameplay. Emits mouse_look_bridge_requested when FPS capture is needed — pair with mouse_capture_look.

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

MANDATORY when UI needs hover — Restores desktop hover/focus affordances mobile never had. Prefer this over ad-hoc mouse_entered dumps.

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

Captured look via InputEventMouseMotion.relative — use for FPS/orbit when adapter alone is not enough.

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

MANDATORY — Windowed / exclusive fullscreen / borderless via DisplayServer.

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

Runtime InputMap remap + ConfigFile persistence.

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

Hardware cursor show/hide/combat vs menu states.

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

VSync / Engine.max_fps unlock for 144Hz+.

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

Native resolution OptionButton from DisplayServer.screen_get_size.

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

MANDATORY — Shrink thumb-sized mobile Controls for mouse density.

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

Mouse-wheel zoom replacing pinch.

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

MANDATORY — set_auto_accept_quit(false) + save prompt on WM close.

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

Launch/place window on the screen under the cursor.

---

Decision Tree — Input Script Picks

| Need | Use |

|------|-----|

| Map touch actions → WASD/mouse without rewriting movers | desktop_input_adapter |

| Button/Control hover styles & tooltips | hover_bridge |

| Captured mouselook (FPS/3P orbit) | mouse_capture_look — MANDATORY when aim/Look requires captured relative motion; adapter get_aim_vector() alone is top-down only |

| Rebindable keys | keybinding_remapper |

| Pinch → wheel zoom | scroll_wheel_zoom |

When desktop_input_adapter emits mouse_look_bridge_requested, attach or enable [mouse_capture_look.gd](scripts/mouse_capture_look.gd) on the player/camera rig — do not stop after InputMap injection.

Port Procedure (ordered)

1. MANDATORY desktop_input_adapter (+ hover_bridge for UI) so every touch action has a precision equivalent.
2. desktop_ui_scaler + expanded layouts (hotbar/chat/minimap) — godot-ui-containers for structure.
3. dynamic_window_manager + multi_monitor_handling + quit_confirmation.
4. resolution_dropdown + uncapped_framerate + graphics quality ladder (persist ConfigFile).
5. Deeper OS integration → godot-platform-desktop.

Platform Services Decision Tree (Steam / Discord)

| Goal | Decision |

|------|----------|

| Ship on Steam with cloud/achievements | Add GDExtension bridge (e.g. GodotSteam); keep init behind OS.has_feature("steam") / editor-safe stubs. Do not paste fake Steam.* tutorials into gameplay scripts. |

| Discord Rich Presence only | Prefer a thin GDExtension/plugin; update presence from an Autoload on scene change — never block _ready on network. |

| No store integration this milestone | Cut — omit Steam/Discord code paths entirely; document as future GDExtension spike. |

Deep Recipes

> MANDATORY when porting beyond the ordered procedure: read [desktop-port-deep.md](references/desktop-port-deep.md). Do NOT Load it for a first-pass keyboard/mouse remap.

Testing (before ship)

> MANDATORY before declaring the port complete: run [desktop-port-testing-checklist.md](references/desktop-port-testing-checklist.md). Do not inline a partial checklist — use the reference file.

Expert Techniques (short)

• Optional lightweight launcher via OS.create_process + user://settings.cfg before main pack.
• Short FPS benchmark → write user://override.cfg quality suggestions.
• Graphics quality ladder (MSAA, shadow atlas, post-FX) and UI density tables live in [desktop-port-deep.md](references/desktop-port-deep.md) — open when port procedure rows are insufficient.

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

• Using InputEvent — Event pipeline for replacing InputEventScreenTouch/ScreenDrag with mouse motion, buttons, and keyboard actions on desktop.
• Mouse and input coordinates — Viewport vs canvas transforms so mouse aim and hover hit the same UI/game space as former touch targets.
• Custom mouse cursor — Hardware cursor shapes and hide/show rules for combat vs menus (Input.set_custom_mouse_cursor).
• Input examples — Practical WASD, mouse-look, and action patterns that map onto mobile virtual-joystick / button actions.
• Handling quit requests — NOTIFICATION_WM_CLOSE_REQUEST / set_auto_accept_quit(false) so the OS close button can prompt save instead of silent exit.
• Multiple resolutions — Stretch mode, aspect, and content scale when leaving fixed mobile base resolutions for 1080p–4K and ultrawide.
• DisplayServer — Window modes, VSync, screen count/size/position, and refresh-rate queries behind fullscreen and multi-monitor ports.
• Window — Per-window size, position, and mode APIs used with borderless / exclusive fullscreen toggles.
• InputMap — Runtime remapping of actions to keycodes so PC players can rebind what mobile hard-coded as touch zones.
• Size and anchors — Anchor/offset contracts when shrinking thumb-sized controls for mouse density without breaking layout.
• Using Containers — Box/Grid/Margin layout rules for expanded desktop HUDs (hotbars, chat, minimap) vs compact mobile stacks.
• Feature tags — pc / mobile / OS tags for branching input, UI scale, and graphics quality without separate projects.

Related Skills

Prerequisites

• godot-input-handling — Shared InputEvent buffering, action maps, and device detection before injecting WASD/mouse equivalents for mobile actions.
• godot-ui-containers — Anchors, containers, and minimum sizes so desktop UI shrink/expand passes keep layout correct across resolutions.
• godot-platform-mobile — Inventory the mobile lifecycle, touch, and safe-area assumptions you are replacing before desktop window/input paths take over.

Complements

• godot-platform-desktop — Deeper Windows/macOS/Linux DisplayServer and OS integration once the mobile→desktop control and settings remap is in place.
• godot-camera-systems — Mouse-look, orbit, and scroll-wheel zoom rigs that replace swipe/pinch camera controls.
• godot-performance-optimization — Profiling and quality ladders when unlocking FPS, MSAA, shadows, and draw distance for desktop GPUs.
• godot-save-load-systems — Durable save ownership hooked to window-close confirmation and settings ConfigFile persistence.
• godot-ui-theming — Theme type variations and hover styles that mobile never showed but desktop players expect on buttons/menus.
• godot-project-foundations — Display stretch, renderer, and feature-tag project defaults that every desktop port branch depends on.
• godot-autoload-architecture — Singleton homes for window managers, input adapters, and graphics settings that must outlive scene changes.

Downstream / consumers

• godot-export-builds — Packaging and CI export presets for Windows/macOS/Linux after input/UI/window gates pass on desktop.
• godot-adapt-desktop-to-mobile — Inverse lattice when the same codebase must keep or regain touch-first paths after a desktop-first pass.
• godot-monte-carlo-balancer — Re-tune difficulty when mouse precision and higher FPS invalidate mobile touch timing and aim curves.

Master

• godot-master — Library router and mirrored module entry for discovering this adapt skill beside sibling domains.