Watch-points for variables

[EternoAprendizBlender]

I'm new to Godot (I've been learning it for about three months), but as far as I know, there is no way to create a watch-point for a variable. Please correct me if I'm wrong.

I have experience programming in SAP with ABAP, where we can set watch-points on variables. These watch-points allow execution to pause at a breakpoint exactly when the variable changes. We can also specify that execution should stop only if the variable takes on a specific value. The debugger then halts on the line immediately after the change occurs.

In Godot, I haven't found a way to achieve this directly. As a workaround, I end up placing breakpoints at every assignment to the variable, which can be tedious when debugging complex cases. I know there are alternatives, such as using a setter with a breakpoint, but as far as I can tell, there isn't a straightforward way to stop execution precisely on the line where the variable's value is modified.

Would it be possible to add native support for watch-points in the debugger? I think this would be a valuable feature for debugging in Godot.

[AThousandShips]

See:

• Add an elegant way to listen to property changes #4868
• Add onset(...) GDScript function to observe changes in script variables #10909
• Add @observable annotation for properties in GDScript #4867

[EternoAprendizBlender]

I have reviewed the three proposals mentioned, but I believe they do not fully address the functionality I am suggesting. My proposal is not just about observing variable changes (like @observable or onset), but about creating a dynamic breakpoint on a variable that only activates under certain conditions, without manually placing breakpoints on every line where the variable is modified.

Summary of the three related proposals and why this is different:

1. #4868 - Elegant way to listen to property changes

Suggests an easier way to listen for property changes, likely through a global function returning a signal.
Key difference: Focuses on listening to changes reactively, rather than halting execution when a variable changes.

2. #10909 - Add onset(...) function

Proposes an onset function to observe changes in script variables, avoiding manual setters and signals.
Key difference: Aims to simplify observing changes but does not provide a debugger integration that stops execution.

3. #4867 - @observable annotation for properties

Suggests an @observable annotation for properties, which would automatically emit a signal when the property changes.
Key difference: Improves reactive programming but does not allow conditional breakpoints on variable changes.

---

What a Watch-Point Would Add to Godot

A watch-point would work as a dynamic breakpoint that activates only when a variable is modified, without requiring breakpoints on every possible assignment across multiple scripts. This would be especially useful for debugging variables passed by reference, where tracking modifications across different scripts is currently tedious.

In SAP, for example, watch-points work as follows:

1. Variable Name: The variable to watch.
2. Program (or script in Godot): Where the variable is declared.
3. Condition (Optional): If left blank, execution stops every time the variable changes. If a logical condition is set, execution stops only when the variable changes and meets that condition.

In a game engine like Godot, where code runs every frame, dozens of times per second, manually placing a breakpoint at every possible assignment of a variable is not an efficient solution. The debugger could stop countless times before reaching the specific situation you need to analyze.

With watch-points, execution would pause at the exact moment the variable changes under the specified conditions, making it much easier to track down issues and debug efficiently.

---

Additional Debugger Suggestion

By the way, I also feel that Godot's debugger is missing a "Step Out" button (see images between SAP and Godot). This button would allow exiting the current function and returning to the caller, making debugging more efficient. It would be great to have this feature added to the debugger.

Currently (I think), the only way to do this seems to be manually going to the stack, selecting the previous function call, and setting a breakpoint there, which becomes very tedious if you need to do it multiple times. A dedicated Step Out button would significantly improve the debugging workflow.

[arkology]

By the way, I also feel that Godot's debugger is missing a "Step Out" button

Tracked in #2815 and will be implemented by godotengine/godot#97758

[dalexeev]

As a workaround, I end up placing breakpoints at every assignment to the variable, which can be tedious when debugging complex cases. I know there are alternatives, such as using a setter with a breakpoint, but as far as I can tell, there isn't a straightforward way to stop execution precisely on the line where the variable's value is modified.

I'm not against watchpoints, I'm just pointing out a workaround. You can use a breakpoint inside the setter and watch the caller in the call stack, you don't have to put a breakpoint on every assignment. Also, you can wrap the breakpoint in some condition, including checking where the setter is called from with get_stack().

var _temp_my_var_setter_trigger_count: int = 0

var my_var: int:
    set(value):
        _temp_my_var_trigger_count += 1
        var stack: Array = get_stack()
        if (
            value > 10
            and stack.size() > 1
            and stack[1].source != "res://definitely_unrelated.gd"
            and _temp_my_var_setter_trigger_count > 3
        ):
            breakpoint
        my_var = value