Skip to content

TauPlot

Inherits: PanelContainer

Root node for creating and displaying plots.

Description

TauPlot is the root node for creating and displaying plots. Add it to your scene, then call a plot-type method to build and display a plot.

Before a plot is created, all provided inputs are validated. This helps catch misconfiguration early and report it through user-friendly warnings or errors.

Once created, a plot remains live. It listens to the dataset and refreshes automatically when the data changes. Configuration and style objects can also be modified at runtime, but require queue_refresh() or refresh_now() to apply. Refreshes are incremental and avoid rebuilding the whole plot when possible.

All plot types share the same high-level container behavior and optional interaction systems:

  • a legend, enabled by default, whose visibility is controlled through legend_enabled and whose placement, flow direction, and appearance are controlled through legend_config
  • a hover inspection system, disabled by default, which can provide tooltips, highlighting, and sample interaction signals

When hover_enabled is true, the plot can detect hovered samples, display tooltips, highlight data, and emit interaction signals. Use hover_config to configure the built-in behavior, or disable the built-in tooltip and drive your own UI from the interaction signals:

XY plots

plot_xy() builds an XY plot from three objects:

The Dataset stores the actual samples. The TauXYConfig defines how the plot is laid out. The TauXYSeriesBinding objects connect both by specifying where and how each dataset series should be rendered.

An XY plot is organized around one shared X axis. This axis spans the whole plot and is configured through TauXYConfig.x_axis_id. Its position determines how panes are arranged:

  • when the X axis is on the top or bottom edge, panes are stacked vertically
  • when the X axis is on the left or right edge, panes are stacked horizontally

A plot may contain one or more panes. Most XY plots need only one pane, but multiple panes are useful when different series should not share the same Y scale, such as a price series above a volume series.

Each pane contains one or more overlays, which are the visual layers that render the data, such as bars or scatter points. A pane also manages its own Y axes independently from the other panes.

Each pane can expose up to two Y axes, placed on the two edges orthogonal to the X axis. For example, if the X axis is on the bottom, the pane may use a left Y axis, a right Y axis, or both. This allows series with very different value ranges to be displayed in the same pane without sharing the same scale.

A series can be bound once or multiple times depending on the intended visualization. See TauXYSeriesBinding for the supported binding rules.

By default, domains and ticks are computed automatically. Each axis scans the data, applies configurable padding, and selects readable tick positions that fit without overlap. When automatic bounds are not desired, TauAxisConfig.range_override_enabled can be used to force a fixed range.

After plot_xy() succeeds, the plot listens to the dataset and refreshes automatically whenever the data changes. The configuration and style objects can also be modified at runtime. In that case, call queue_refresh() to apply the changes.

Hover inspection

When hover_enabled is true, the plot can detect hovered samples, show tooltips, and emit interaction signals.

Use hover_config to customize the built-in behavior, or leave the tooltip disabled and drive your own UI using:

Quick usage

  1. Add a TauPlot node to your scene.
  2. Build a Dataset.
  3. Build an TauXYConfig.
  4. Create one TauXYSeriesBinding per plotted series.
  5. Call plot_xy().

Example

    var dataset := TauPlot.Dataset.make_shared_x_categorical(
        PackedStringArray(["Revenue", "Costs"]),
        PackedStringArray(["Q1", "Q2", "Q3", "Q4"]),
        [
            PackedFloat64Array([120.0, 135.0, 148.0, 160.0]),
            PackedFloat64Array([90.0, 95.0, 100.0, 108.0]),
        ]
    )

    var x_axis := TauAxisConfig.new()
    x_axis.type = TauAxisConfig.Type.CATEGORICAL

    var y_axis := TauAxisConfig.new()
    y_axis.title = "EUR"

    var bar_overlay_config := TauBarConfig.new()

    var pane := TauPaneConfig.new()
    pane.y_left_axis = y_axis
    pane.overlays = [bar_overlay_config]

    var config := TauXYConfig.new()
    config.x_axis = x_axis
    config.panes = [pane]

    var b0 := TauXYSeriesBinding.new()
    b0.series_id = dataset.get_series_id_by_index(0)
    b0.pane_index = 0
    b0.overlay_type = TauXYSeriesBinding.PaneOverlayType.BAR
    b0.y_axis_id = TauPlot.AxisId.LEFT

    var b1 := TauXYSeriesBinding.new()
    b1.series_id = dataset.get_series_id_by_index(1)
    b1.pane_index = 0
    b1.overlay_type = TauXYSeriesBinding.PaneOverlayType.BAR
    b1.y_axis_id = TauPlot.AxisId.LEFT

    var bindings: Array[TauXYSeriesBinding] = [b0, b1]

    $MyPlot.title = "Quick Start Example"
    $MyPlot.plot_xy(dataset, config, bindings)

Common workflows

Update the data
Mutate the Dataset. The plot refreshes automatically when the dataset emits changed.

Change plot configuration at runtime
Mutate the objects passed to plot_xy(), then call queue_refresh().

Replace the current plot
Call plot_xy() again. The current plot is cleared automatically before the new one is built.

Reset the plot
Call reset().

Notes

  1. plot_xy() replaces the active plot. Calling it while a plot is already displayed tears down the current plot before building the new one. The previous dataset is disconnected automatically.

  2. Validation errors abort without modifying the current plot. If validation finds errors, plot_xy() logs them and returns, leaving the existing plot in place. Validation warnings are logged but do not abort.

TauPlot Namespace

TauPlot is registered as a global class, so it can be referenced directly anywhere in GDScript.

Most supporting types in the addon are intentionally not registered as global classes to avoid cluttering the global class namespace. Instead, they are exposed as constants on TauPlot. This makes the most common TauPlot types available from a single access point without requiring separate preload() calls.

Reference them as TauPlot.ClassName, for example TauPlot.Dataset.new() or TauPlot.ColorBuffer.new().

The types listed below are available through this namespace.

  • Dataset Holds all X and Y sample data for one or more named series and notifies the plot of every change.
  • VisualAttributes Abstract base class for data-oriented per-sample style override buffers.
  • BarVisualAttributes Per-sample style override buffers for BAR overlays.
  • ScatterVisualAttributes Per-sample style override buffers for SCATTER overlays.
  • VisualCallbacks Abstract base class for callback-driven per-sample style overrides.
  • BarVisualCallbacks Callback-driven per-sample style overrides for BAR overlays.
  • ScatterVisualCallbacks Callback-driven per-sample style overrides for SCATTER overlays.
  • SampleHit Read-only description of one sample detected near the cursor during hover hit testing.
  • ColorBuffer Ring buffer storing Color values with a fixed capacity.
  • Float32Buffer Ring buffer storing float values (32-bit) with a fixed capacity.
  • Float64Buffer Ring buffer storing float values (64-bit) with a fixed capacity.
  • Int32Buffer Ring buffer storing int values (32-bit) with a fixed capacity.
  • StringBuffer Ring buffer storing String values with a fixed capacity.

Enums

AxisId

Identifies an axis by the edge position it occupies on the plot.

Value Meaning
BOTTOM The bottom edge position.
TOP The top edge position.
LEFT The left edge position.
RIGHT The right edge position.

PaneOverlayType

Identifies the visual layer type used to render series data inside a pane.

Value Meaning
BAR Bar overlay. Renders each sample as a bar originating from zero.
SCATTER Scatter overlay. Renders each sample as a marker at its data position.

Signals

sample_hovered()

signal sample_hovered(hits: Array[SampleHit])

Emitted when the mouse moves over one or more samples. hits contains one SampleHit per detected sample. In NEAREST mode the array contains one entry. In X_ALIGNED mode it may contain one entry per series at the nearest X position. For PER_SERIES_X datasets, only series that have a data point at the globally nearest X value are included, so the array often contains a single entry. Requires hover_enabled to be true.

sample_hover_exited()

signal sample_hover_exited()

Emitted when the mouse leaves all sample hit zones. Requires hover_enabled to be true.

sample_clicked()

signal sample_clicked(hits: Array[SampleHit])

Emitted on a mouse click over one or more samples. hits follows the same content rules as sample_hovered. Requires hover_enabled to be true.

sample_click_dismissed()

signal sample_click_dismissed()

Emitted when a pinned tooltip is dismissed by clicking on empty space or by pressing Escape. Requires hover_enabled to be true.

Properties

title

title: String

Sets the title displayed above the plot. Supports BBCode. Defaults to "", which hides the title. Updates immediately when the node is inside the scene tree.

hover_enabled

hover_enabled: bool

Master switch for the hover inspection system. When false, no hit testing runs, no hover signals fire, and no tooltip, crosshair, or highlight renders. When true, the system activates using the settings in hover_config. Defaults to true. Safe to set after plot_xy().

hover_config

hover_config: TauHoverConfig

Configuration for the hover inspection system. Controls hover mode, tooltip, crosshair, highlight, and formatting callbacks. If null, built-in defaults apply for all settings. Defaults to null. Safe to set after plot_xy().

legend_enabled

legend_enabled: bool

Controls legend visibility. When true, the legend renders using the settings in legend_config. When false, the legend is hidden. Defaults to true.

legend_config

legend_config: TauLegendConfig

Configuration for the legend system. Controls position, flow direction, and visual style. If null, built-in defaults apply for all settings. Defaults to null. Safe to set after plot_xy().

Methods

Plot lifecycle

plot_xy()

plot_xy(p_dataset: Dataset, p_xy_config: TauXYConfig, p_series_bindings: Array[TauXYSeriesBinding]) -> void

Builds and displays an XY plot.

Validates all inputs before making any change (see Note 2). On success, tears down any active plot, builds renderers, axes, panes, the legend, and the hover controller, subscribes to p_dataset.changed, and schedules the first render. The plot keeps references to the provided parameters. Mutating them after plotting is supported, but requires queue_refresh() or refresh_now() to apply the changes.

Parameters

  • p_dataset: Dataset The data model. The plot holds a reference and subscribes to its changed signal for the lifetime of this plot. Must not be null.
  • p_xy_config: TauXYConfig Defines the X axis, pane layout, overlay configurations, and visual settings. Must not be null.
  • p_series_bindings: Array[TauXYSeriesBinding] One entry per series-to-pane mapping. Each entry specifies a series_id, a pane_index, an overlay_type, and a y_axis_id. Must not be null.

reset()

reset() -> void

Destroys the active plot and resets the node to an empty state.

Frees all renderer nodes, disconnects dataset and style signals, and hides the title. Safe to call when no plot is active.

queue_refresh()

queue_refresh() -> void

Schedules a render update for the next frame.

If a refresh is already pending, does nothing. Call this after mutating configuration or style properties on the objects passed to plot_xy() to apply the changes.

refresh_now()

refresh_now() -> void

Forces an immediate refresh in the current frame. Use this only when the plot needs to be up to date synchronously. For most UI-driven updates, prefer queue_refresh(), since theme and layout changes may settle on the next frame.