DevLog 2025801: Procedural Context Type

Sat, 02 Aug 2025 01:47:41 +0000

Overview

In our pursuit to challenge existing visual paradigms and establish the next-generation general-purpose visual programming system, we've studied, borrowed from, and questioned many design elements of existing systems.

An area of innovation in Divooka is its hybrid use of dataflow and procedural contexts - each suited for particular use cases.

Another innovation, still in its infancy and improving through trial and error, is what we call the procedural context base type.

Introduction

The need for this concept emerged as we integrated procedural contexts and re-examined the pain points of working with advanced visual programming systems like Unreal Blueprint. Changing the base type of Blueprints often leads to disastrous outcomes.

We aim to provide a smoother experience. In Divooka, the procedural "base type" is a toggle - you can quickly switch a graph to a different base type. Everything that isn't type-dependent continues to work, and any function that is type-dependent simply indicates so.

Components

The procedural base type introduces four important concepts:

Procedural base type (current anchor): The current graph's base, representing the instance that functions in the graph are called on.
Procedural runner for any given base type: When a run is triggered, Divooka allows a custom runner to determine what actually happens. In a typical program, this runner might seek the "entry" function (e.g., Start) and execute from there. In higher-level frameworks, it might look for recognizable event bindings.
Procedural base type instance override: By default, the specified base type is instantiated at runtime to provide a concrete instance. However, the runtime can also supply a compatible instance for the graph's behavior to operate on. This allows flexibility and decouples implementation (runtime instance) from behavior specification (graph design).
Divooka graph-baked procedural instance type: It may be desirable to directly convert or interpret a graph as a concrete type. The main benefit is being able to pass the graph as a type for further processing. This feature is not yet implemented.

Based on the above, three key objects are involved in evaluating a procedural context graph:

Executer: Provides the logic and mechanisms to fetch and evaluate specific execution paths in the procedural graph.
Runner: Determines what to run and in what order, on an event level. It may also provide additional runtime data required by the instance.
Instance: Represents the runtime state of the graph.

Summary

In summary, a Divooka graph is a data structure that specifies behavior, while the runtime interprets and is responsible for actual execution. This makes Divooka a data-driven and highly extensible programming system suitable for various scenarios.

By combining the scripting nature of Divooka graphs with the compiled/JIT-accelerated nature of the runtime, Divooka offers both flexibility and dynamic richness - while minimizing friction in program development.

DevLog 20250708: Procedural Context Visual Debugger in Divooka

Tue, 08 Jul 2025 12:19:17 +0000

Overview

How difficult is it to achieve Unreal Engine-style procedural context debugging?

Turns out, it might be easier than expected.

In this dev log, we won't implement all the fancy animations or full-featured GUI yet, but we will derive a practical, functional debugger GUI. This interface allows users to step through a procedural program and observe its execution flow in real time.

The Debugging Problem

Procedural contexts are hard - not necessarily to implement (they're actually simpler than dataflow contexts in interpretative runtimes, where you just step over nodes), but hard for users.

The main issue is statefulness: once there's state, there's the potential for mistakes, side effects, and confusion.

From an implementation standpoint, the hard part is debugging. Without visibility into execution, it's difficult to guess what's happening. That's why programming languages without IDEs often fall back on Print statements to inspect runtime states. This approach quickly breaks down with larger programs or those involving intricate state transitions.

Even Python - often used without an IDE - includes a built-in debugger in IDLE (see tutorial). It's essential when working with complex logic.

Approach

Let's start by clarifying the setup: the current implementation of the Divooka graph editor (Neo) is done in WPF, using an interpretative runtime.

For drawing the GUI, we can use standard XAML data bindings and a few button states:

<StackPanel>
<!--Start-->
<Button Style="{StaticResource IconButtonStyle}" Click="ProceduralContextRunGraphWithoutDebugging_Clicked" ToolTip="Run and wait for the process to finish." Visibility="{Binding EvaluatingGraph, Converter={converters:BooleanToVisibilityConverter Negate=True}}"/>

<!--Continue-->
<Button Style="{StaticResource DebugButtonStyle}" Content="Continue" Click="ProceduralContextContinueWithoutStepping_Clicked" ToolTip="Skip debugging and continue the process to completion." Visibility="{Binding IsProceduralStepping, Converter={converters:BooleanToVisibilityConverter}}"/>

<!--Step-->
<StackPanel Visibility="{Binding EvaluatingGraph, Converter={converters:BooleanToVisibilityConverter Negate=True}}">
<Button Style="{StaticResource DebugButtonStyle}" Content="Step" Click="ProceduralContextStartDebuggingGraph_Clicked" ToolTip="Step into the process and observe each execution step." Visibility="{Binding IsProceduralStepping, Converter={converters:BooleanToVisibilityConverter Negate=True}}"/>
</StackPanel>

<!--Next Step-->
<Button Style="{StaticResource DebugButtonStyle}" Content="Next" Click="ProceduralContextContinueThroughGraph_Clicked" ToolTip="Execute (step over) the next step in the process."  Visibility="{Binding IsProceduralStepping, Converter={converters:BooleanToVisibilityConverter}}" IsEnabled="{Binding IsProceduralPaused}"/>

<Button Style="{StaticResource DebugButtonStyle}" Content="Finish" Click="ProceduralContextFinishDebuggingGraph_Clicked" ToolTip="Stop debugging the current process." Visibility="{Binding IsProceduralStepping, Converter={converters:BooleanToVisibilityConverter}}"/>

<Button Style="{StaticResource DebugButtonStyle}" Content="Pause" Click="ProceduralContextPauseExecution_Clicked" ToolTip="Pause execution of the current process." Visibility="{Binding EvaluatingGraph, Converter={converters:BooleanToVisibilityConverter}}" IsEnabled="{Binding IsProceduralPaused, Converter={StaticResource InvertBooleanConverter}}"/>
</StackPanel>

Stepping Through Execution

Initially, I thought we needed a dedicated execution runtime for stepping, due to the complexity of node interpretation. However, it turns out we can simply inject "breakpoints" during interpretation. The simplest way to achieve this in C# with multithreading is by using a ManualResetEventSlim:

// ── MainWindow.xaml.cs (WPF) ──
public partial class MainWindow : Window
{
// starts signaled (i.e. not paused)
    private readonly ManualResetEventSlim _pauseEvent = new ManualResetEventSlim(true);
    private readonly Executer _executer;

    public MainWindow()
    {
        InitializeComponent();
        _executer = new Executer(_pauseEvent);
    }

    private async void StartButton_Click(object sender, RoutedEventArgs e)
    {
// Run on thread-pool, but because we 'await', continuation
        // (Finish…) runs back on the UI thread.
        await Task.Run(() => _executer.ExecuteGraph());
        FinishProceduralContextDebuggingSession();
    }

    private void PauseButton_Click(object sender, RoutedEventArgs e)
    {
// next time the worker hits Wait(), it will block
        _pauseEvent.Reset();
    }

    private void ResumeButton_Click(object sender, RoutedEventArgs e)
    {
// unblocks the worker
        _pauseEvent.Set();
    }
}

// ── Executer.cs ──
public class Executer
{
    private readonly ManualResetEventSlim _pauseEvent;
    private readonly Random _random = new Random();

    public Executer(ManualResetEventSlim pauseEvent)
    {
        _pauseEvent = pauseEvent;
    }

    public void ExecuteGraph()
    {
        while (/* your long-running condition */)
        {
            DoWorkStep();  

// simulate a random pause point
            if (_random.NextDouble() < 0.05)
            {
                Debug.WriteLine("…pausing now");
// put event into non-signaled (i.e. paused)
                _pauseEvent.Reset();
                _pauseEvent.Wait();  // block until resumed
                Debug.WriteLine("…resumed!");
            }
        }
    }

    private void DoWorkStep()
    {
        Thread.Sleep(200);
    }
}

How It Works:

_pauseEvent starts in the signaled state, so .Wait() returns immediately.
Calling _pauseEvent.Reset() switches it to non-signaled, so .Wait() blocks the worker thread.
When the UI calls _pauseEvent.Set(), the blocked thread resumes execution.

Real-Time Visual Updates

A small challenge is real-time canvas updates - specifically, drawing a highlight box around the active node:

We can use an adorner for this:

/// <summary>
/// Show a red highlight around the specified FrameworkElement for a set duration.
/// </summary>
public static async void ShowSimpleHighlight(FrameworkElement target, double margin = 5, int duration = 3)
{
    if (target == null)
        return;

// Get the adorner layer for that target
    AdornerLayer adornerLayer = AdornerLayer.GetAdornerLayer(target);
    if (adornerLayer == null)
        return;

// Create and add adorner to the layer
    HighlightAdorner highlightAdorner = new(target, margin);
    adornerLayer.Add(highlightAdorner);

// Remove it after a few seconds
    await Task.Delay(TimeSpan.FromSeconds(duration));
    adornerLayer.Remove(highlightAdorner);
}

public class HighlightAdorner : Adorner
{
    private readonly Pen _pen;
    private readonly double _margin;

    public HighlightAdorner(UIElement adornedElement, double margin = 5)
        : base(adornedElement)
    {
        _pen = new Pen(Brushes.Red, 2);
        _pen.Freeze();
        _margin = margin;
        IsHitTestVisible = false;
    }

    protected override void OnRender(DrawingContext drawingContext)
    {
        Rect adornedElementRect = new(AdornedElement.RenderSize);
        adornedElementRect.Inflate(_margin, _margin);
        drawingContext.DrawRectangle(null, _pen, adornedElementRect);
    }
}

What's Next?

All that's left is a proper debug window!

Summary

A good framework truly goes a long way. I had confidence in bringing procedural debugging to Divooka from the moment procedural context was introduced, because it naturally fits into an interpretative execution model. All that's required is a bit of focused engineering.

The more challenging part is the GUI - but WPF offers solid isolation via MVVM, data binding, and adorners.

We're not dealing with setting actual breakpoints yet, but the current setup is flexible enough to support that when the time comes. Ultimately, a debug window will act as our lens into the runtime: inspecting node states, variable values, and control flow.

References

Procedural vs Dataflow context in Divooka on the Methodox Wiki.
Blueprint debugging in Unreal
Procedural debugging documentation on Methodox Wiki.

Coder Legion - Recent posts tagged procedural

DevLog 2025801: Procedural Context Type

Overview

Introduction

Components

Summary

DevLog 20250708: Procedural Context Visual Debugger in Divooka

Overview

The Debugging Problem

Approach

Stepping Through Execution

Real-Time Visual Updates

What's Next?

Summary

References