Introduction

In DSH, the common approach to having an agent interact with a Godot project is to use a godot-mcp MCP service: an extra protocol layer, an additional Python/Node process, and a separate editor plugin to maintain. On the game side, although there is already a McpInteractionServer listening on 127.0.0.1:9090 for newline-separated JSON, the harness side still needs to communicate via an MCP intermediary.

godot-bridge consolidates this chain into the DSH host plugin: no MCP, no standalone Python service, no editor addon modifications. The host directly spawns the Godot process and communicates with the in-game autoload via a short-lived TCP connection. Tools are registered into the session with the godot_* prefix. Below, we introduce its positioning, capabilities, and installation method.

What It Is

godot-bridge is a native DeepSeek Harness plugin released by maintainer Smalldy (GitHub: Smalldy/godot-bridge, current package version 0.1.5, MIT license). It is classified as a workflow plugin.

In one sentence: It launches and drives a running Godot 4.x game within a DSH session. It uses the same in-game TCP interaction service protocol as godot-mcp, but replaces the MCP service with first-class agent tools.

How It Works

The game project must have the McpInteractionServer autoload (mcp_interaction_server.gd), which by default listens on 127.0.0.1:9090 and exchanges newline-separated JSON messages. godot-bridge operates within the harness as follows:

  1. godot_run_project launches a debug process with godot -d --path …, waiting for port 9090 to become ready.
  2. godot_command, godot_screenshot, godot_ping, etc., use a one-shot node -e bridge to connect to TCP, send a single command, read a single response line, and then exit. This adapts to the server’s single-connection, single-command _busy semantics.
  3. Headless editing operations use scripts like godot --headless --script godot_operations.gd, requiring no active game process.

Spawning uses the harness’s raw subprocess service (not a sandboxed shell), ensuring that Godot can write to paths like user:// without being blocked by the DSH file sandbox.

If the project does not yet have McpInteractionServer, godot_run_project will automatically copy the vendored file to autoload/ and register it in project.godot. Non-Godot projects are unaffected.

Core Tools

The README lists each tool alongside its godot-mcp counterpart; here, we categorize the verified capabilities by usage.

Running Game (TCP 9090)

Tool Function
godot_run_project Launches the project in debug mode, waiting for port 9090
godot_stop_project Terminates the launched game process (tree-range kill)
godot_get_debug_output Incrementally reads child process stdout/stderr
godot_command Sends arbitrary commands to the interaction service (consolidating about 130 game_* capabilities): get_scene_tree, eval, get/set_property, call_method, click, key_press, screenshot, raycast, serialize_state, ui_*, etc.
godot_screenshot Viewport screenshot, base64 PNG
godot_ping Probes if 9090 is responding; includes installed/latest plugin version info

Headless & Project Static Operations

Tool Function
godot_headless_op 16 headless static operations (read/modify scene nodes, attach scripts, create resources, save scenes, etc.), no running game required
godot_validate_script Headless GDScript compilation check, returns {valid, errors}
godot_set_project_setting Writes arbitrary key-value pairs to sections in project.godot based on type
godot_manage_autoloads Lists/adds/removes autoload singletons
godot_manage_input_map Lists/adds/removes input actions (uses Godot 4 key codes, fixing the Godot 3 baseline issue in godot-mcp)
godot_manage_export_presets Manages export_presets.cfg
godot_create_script Generates GDScript templates
godot_create_project Scaffolds a project, with optional Godot .NET .csproj
godot_export_project Headless export (--export-release / --export-debug)

Configuration

Tool Function
godot_set_engine_path Writes the path to the Godot executable into settings (godotPath in the godot-bridge: section of settings.yaml), hot-reloadable

Pure file read/write operations are covered by DSH’s native file tools. Items requiring Godot-specific syntax (input mappings, export presets, project.godot types, etc.) are handled by the specialized tools above. For a complete mapping, see COVERAGE.md in the repository.

Requirements

  1. DeepSeek Harness installed (session with host runtime).
  2. Godot 4.x executable: Priority is tool parameter godot_path → setting godotPath → godot command on PATH. Use the full path to the real executable, avoiding version manager shims.
  3. node on PATH (used for one-shot bridge connections).
  4. The target Godot project must have or be able to auto-install the McpInteractionServer autoload.

Installation & Enabling

The plugin must be installed via the DSH bundle mechanism; do not copy it to ~/.dsh/.agent-presets/... (which cannot resolve @deepseek-ai/dsh-tools).

Recommended one-liner (requires dsh CLI):

dsh plugin --profile web add github:Smalldy/godot-bridge

dsh plugin forwards to pnpm: it installs into the profile’s node_modules and writes tool-godot-bridge into the profile’s dsh.profile.bundles via cordis.patch.yml. web is the default profile for Web applications; no new profile is created. After restarting DSH, sixteen godot_* tools will be visible in sessions under that profile.

Local paths or tarballs are also supported:

dsh plugin --profile web add ./path/to/godot-bridge

Uninstall:

dsh plugin --profile web remove godot-bridge

First, use godot_stop_project to stop the game. After uninstalling and restarting, the tools are removed from the session, but the web profile itself remains unchanged.

Update:

dsh plugin --profile web update godot-bridge

The plugin performs a best-effort comparison with the package.json version on GitHub main upon loading. If an update is available, the system will show a prompt: “godot-bridge update available: installed X, latest Y”. godot_ping also reports plugin_version / latest_version.

For community registration, see awesome-dsh-plugin (topic: dsh-plugin).

Typical Usage

1. Specify Godot Path (When godot is Not on PATH)

Have the model ask the user and then call godot_set_engine_path, or configure the godotPath in the godot-bridge: section of the Web plugin page / settings.yaml.

2. Launch Project & Check Readiness

godot_run_project   # project_path points to the Godot project root
godot_ping          # Confirm 9090 is responding

3. Query Scene & Interact

Send JSON line protocols identical to godot-mcp via godot_command, for example:

{"command": "get_scene_tree", "params": {}, "id": "1"}

Other common commands include get_ui_elements, eval, click, key_press, serialize_state, etc.; refer to the interaction service implementation for specific parameters.

4. Screenshot

godot_screenshot directly returns a base64 PNG, equivalent to godot-mcp’s game_screenshot.

5. Headless Scene Modification / Script Validation

When the game does not need to be running:

  • godot_headless_op: Static editing of scenes and resources.
  • godot_validate_script: Compile-checks GDScript.
  • godot_set_project_setting, godot_manage_autoloads, godot_manage_input_map: Modify project.godot and related configurations.

6. View Debug Output

godot_get_debug_output incrementally fetches child process logs by offset, useful for debugging with godot_run_project.

Suitable Scenarios & Considerations

Who Is It For

  • Those already using agents in DSH to develop or test Godot 4.x games/tool projects.
  • Those looking to remove the godot-mcp MCP layer while preserving the workflow with the existing McpInteractionServer and 9090 protocol.
  • Those needing headless editing of project.godot, input mappings, and export presets, all within the same set of godot_* tools as controlling the running game.

Considerations

  1. The plugin runs child processes and file operations with the current DSH process permissions. Read the source code and MIT license before installation to ensure it aligns with your security policy.
  2. Do not use version manager shims for the Godot path; otherwise, spawning or user:// behavior may be abnormal.
  3. Interaction service single connection: Relies on the short-lived bridge design; avoid occupying the same TCP session for extended periods.
  4. The SkillHub directory page (skillhub.cn) is a community index and has no official affiliation with DeepSeek /幻方; installation commands are subject to the README and dsh plugin.

Conclusion

godot-bridge connects Godot 4.x’s in-game TCP protocol directly to the DSH host, using sixteen native tools to cover the main workflow of godot-mcp, and adds Godot 4-specific capabilities like input mapping. If you are already doing Godot agent workflows in the harness, you can install it via the official bundle command into the web profile for a trial.

  • Directory page: https://www.skillhub.cn/plugins/Smalldy/godot-bridge
  • GitHub: https://github.com/Smalldy/godot-bridge