Godot 4 Universal Debug Context Menu (DebugMenu)

A lightweight, decoupled, and universal context-menu utility for Godot 4. Designed to handle 2D, 3D, and UI Control nodes alike, it automatically inspects the mouse target and pops up a contextual menu only if the target explicitly defines custom debug actions.

✨ Features

• Universal Mouse Picking: Seamlessly detects clicked targets across 3D physics (Camera3D raycasting), 2D physics (Viewport point queries), and UI layers (Control hover detection).
• Strict Opt-In Architecture: Context menus only open if a node explicitly implements custom debug hooks (get_debug_options() or custom_debug_options), keeping normal gameplay interactions completely undisturbed.
• Fully Decoupled: Operates as a self-contained module with zero hard dependencies on external singletons, utilities, or default fallback actions.
• Direct Action Delegation: Seamlessly routes selected menu item IDs back to the target node via execute_debug_action(id).

📦 Installation & Setup

1. Create a folder in your project directory (e.g., res://scripts/utils/).
2. Add the core script file: debug_menu.gd.
3. Add it as an AutoLoad singleton (e.g., named DebugMenu) or place it directly into your main scene tree.

🚀 Usage Guide

1. Configuring the Debug Menu

You can configure global settings directly in the inspector or via exported script properties:

• enabled: Globally enables or disables right-click context menu processing.
• require_shift: When true, requires the user to hold down the Shift key alongside a right-click to trigger the menu.

2. Making Any Node Debuggable

To enable the context menu for a specific node (whether it's a CharacterBody2D, MeshInstance3D, or a custom Control), simply implement the debug option interface methods:

extends CharacterBody2D

# 1. Returns a list of explicit debug actions for the context menu
func get_debug_options() -> Array:
    return [
        {"label": "Heal to Full", "id": 100},
        {"label": "Spawn Minion", "id": 101}
    ]
    extends Node3D

# Or define your debug options directly as a property array (can also be @export-ed!)
var custom_debug_options: Array = [
    {"label": "Reset Position", "id": 200},
    {"label": "Toggle AI State", "id": 201}
]

# 2. Handles execution when a custom debug option is selected
func execute_debug_action(id: int) -> void:
    match id:
        100:
            print("[Player] Debug action: Restored full health.")
        101:
            print("[Player] Debug action: Spawned minion at position.")

📚 Script Reference

DebugMenu.gd

The universal right-click orchestrator component.

📝 License

Distributed under the MIT License. Feel free to use this in your own personal or commercial Godot projects.