Remote Deploy

---
name: remote-deploy
description: "Run or test the game on a real phone, tablet or computer with Remote Deploy and on-device debugging."
license: MIT
compatibility: [Cursor, Claude Code, Windsurf, Codex]
category: deployment
user-invocable: true
allowed-tools: Read Grep Edit summer_project_setting summer_get_diagnostics summer_get_console summer_get_script_errors
paths: ["project.godot", "export_presets.cfg"]
---

# /remote-deploy — Test the Game on a Real Device

## Overview

Remote Deploy runs the game on an actual target device — a phone, tablet, or another machine — instead of inside the editor. It exports a **debug** build, installs and launches it on the device, and connects the running game back to the editor's debugger so the Output panel, errors, breakpoints, and profiler all work exactly like a local run.

**Capability gate comes first:** before adding a Runnable preset or telling the
user to pick a device, check the installed Summer Engine's export templates and
the platform toolchain. Remote Deploy exports a debug build, so it needs the
debug template for that platform. `summer_export_templates` with
`action: "list"` shows what is installed and published; `action: "install"`
with `includeDebug: true` adds missing ones. Android and iOS also need their SDK
toolchain and signing. Never recommend or attempt a Remote Deploy target that
has not passed this check.

It is **not** the same as two neighbours:

| Action | What it does | Use it for |
|---|---|---|
| **Play** (▶) | Runs in the editor (embedded or windowed) | Fast iteration on the dev machine |
| **Remote Deploy** | Debug build → installs + runs on a device, remote-debugged | Testing real input/perf/screen on hardware |
| **Release export** (`export-and-ship`) | Supported local release builds | Preparing an artifact for a separate user-controlled distribution workflow |

If the user wants a release build for Steam / itch / the App Store, that is `export-and-ship`, not this.

## Where it is in the UI

- **Agent-layout topnav:** the button with the remote-play icon, immediately right of the **Play/Stop** button and the **`▾`** run-options dropdown. Hover tooltip reads **"Remote Deploy"**.
- Clicking it opens a **dropdown of detected targets**, grouped by platform (e.g. an `Android` header with each connected device under it). Picking a target deploys and runs there.
- It is **disabled (greyed out)** with the tooltip **"No Remote Deploy export presets configured."** until the prerequisites below are met. A greyed button is the most common question; it almost always means "no runnable preset or no device detected," not a bug.

## Step 1 — prove the requested target is available

Run `summer_export_templates` with `action: "list"`, then check the requested
platform toolchain. Report one of:

- `available`: the matching debug template and toolchain are present;
- `blocked`: name the missing template, toolchain, signing, or device
  prerequisite;
- `impossible on this build`: Web on the stock Mono build.

Stop on `impossible`. On `blocked`, install the missing template (`summer_export_templates`
`action: "install"`, `includeDebug: true`) after the user agrees, or route the
user to the toolchain setup. Do not add a preset as if that made the target
runnable.

## Step 2 — prerequisites for a proven target

The button auto-enables the moment a runnable preset **and** at least one detected target both exist for the same platform.

| Requirement | How to satisfy it | Why it matters |
|---|---|---|
| A **proven template and toolchain** | Complete step 1 | Without both, a visible target still fails at deploy time. |
| A **runnable export preset** for that proven platform | Project → Export → add the proven preset → toggle **Runnable** on | A preset that exists but isn't marked Runnable does **not** count. |
| A **detected target** | For example, an authorized Android device or a connected, trusted iOS device | The button enables only when at least one target is reported for a runnable platform. |

**Note:** the button does **not** pre-check that templates/toolchain are installed. Enable state is gated only on *runnable preset + detected target*. If templates or the toolchain are missing, the deploy **fails at run time** and the errors appear in a result dialog. So:

> **Runnable preset + a detected device make the button appear/enable. Installed export templates make the deploy actually succeed.**

This matters when guiding a user mid-setup (e.g. building out a mobile flow): you can see the button enable as soon as a phone is plugged in and the preset is Runnable, even before templates finish downloading.

## Step 3 — deploy after proof (the flow)

1. The editor continuously polls the export platforms and rebuilds the dropdown: each runnable platform, with each of its detected devices listed underneath.
2. The user picks a target. Summer Engine exports a **debug** build for that
   preset when the matching template and toolchain are installed.
3. The build is installed and launched on the device (e.g. `adb install` + launch for Android).
4. The running game opens a **remote-debug** connection back to the editor — Output, the debugger, and the profiler reflect the on-device session. Stop it from the editor like any normal run.
5. Any export/deploy error (missing template, no toolchain, unsigned build, device went away) is surfaced in a **result dialog**. Read it; it names the prerequisite to fix.

## Mobile paths after capability proof

**Android**
1. First prove a matching Android template, Android SDK, `adb`, and debug
   signing are installed. Otherwise stop.
2. Enable Developer Options → USB debugging on the phone; plug it in; accept the "Allow USB debugging?" prompt.
3. Confirm `adb devices` lists it as `device` (not `unauthorized`).
4. Project → Export → Android preset → **Runnable** on.
5. The phone appears in the Remote Deploy dropdown → pick it.

**iOS**
1. First prove a matching iOS template, Xcode toolchain, and signing identity
   are installed. Otherwise stop.
2. Connect and trust the device; ensure a valid signing team in the iOS preset.
3. The device appears in the dropdown → pick it.

**Web**

Web is unavailable on the stock Summer Mono build. Do not add a Web Runnable
preset or direct the user to a browser target. Use ordinary local Play for a
sanity check, or first provision and verify a separate non-Mono-compatible
export environment.

## Guiding the user (orchestrator playbook)

When a user says "deploy to my phone" / "run this on device" and the button is greyed:

1. **Prove target capability first** — check the matching debug template
   (`summer_export_templates`) and the platform toolchain. Stop or route
   externally if either is absent; Web is impossible on the stock Mono build.
2. **Check the build is healthy** — a project with script errors won't export.
   - `summer_get_script_errors` and `summer_get_diagnostics` clean? If not, fix those before anything else.
   - `summer_get_console` for "import failed" noise.
3. **Confirm a runnable preset exists** for the proven target platform — Read/Grep `export_presets.cfg` for the platform and a `runnable=true` entry. If missing, walk them through Project → Export → add preset → mark Runnable.
4. **Confirm the main scene is set** — `summer_project_setting` / `project.godot` `application/run/main_scene`. A deploy to a blank main scene launches to nothing.
5. **Confirm a device is detected** — plugged in, debugging enabled, authorized.
6. Then point them at the topnav **Remote Deploy** button → pick the device.

Order matters: capability proof → healthy project → preset → device. The
button can enable before the build is actually possible, so its visible state
never replaces the proof.

## Common mistakes

- **Confusing it with shipping.** Remote Deploy makes *debug* builds for testing. Store/distribution builds are `export-and-ship`.
- **Preset exists but isn't Runnable** → button stays greyed. The Runnable toggle is the gate, not the preset's existence.
- **Expecting it to work without export templates** → button may be enabled (device detected) but the deploy then fails in the result dialog. Install templates.
- **Android device `unauthorized`** in `adb devices` → the device won't show as a target. Re-accept the USB-debugging prompt on the phone.
- **Trying to script it via MCP** — there is no `summer_*` tool that triggers Remote Deploy; it is a UI action. The orchestrator's job is to get the prerequisites green and point the user at the button.

## Quick reference

| Button state | Meaning | Fix |
|---|---|---|
| Greyed, "No Remote Deploy export presets configured." | No runnable preset **or** no detected device | Add a Runnable preset; connect/authorize a device |
| Enabled, dropdown lists devices | Ready to deploy | Pick a device to build + run |
| Deploy fails in result dialog | Templates/toolchain/signing/device issue | Read the dialog; install the named missing piece |

<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
## From a shell

No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.

| In this skill | Command |
|---|---|
| `summer_export_templates` | `summer engine export-templates` |
| `summer_get_console` | `summer engine get-console` |
| `summer_get_diagnostics` | `summer engine get-diagnostics` |
| `summer_get_script_errors` | `summer engine get-script-errors` |
| `summer_project_setting` | `summer engine project-setting` |
<!-- /shell-commands -->