02. Variables tool: Blackboard

I. Introduction to Blackboard

1.1 Purpose: Fast creating and access to global data.

The Blackboard tool (Singleton: NexusForge.Blackboard, Class: BlackboardData) is the central, reliable manager for all game-wide variables, settings, and global state (the "global memory" of the game).

It provides a single source of truth for dynamic data that is accessible across all game systems and tools.

1.2 Design philosophy:

• Availability: Provide a way to set and share data between different modules seamlessly.
• Interactivity: Blackboard is accessed by Discourse to allow for the creation of dynamic dialogues.
• Quick access: Blackboard uses a 2-level nested dictionary and StringNames to access its data, making it quick and efficient compared to other global data managers.
• Dynamic: Blackboard is designed to mimic a directory browser, allowing you to create folders full of variables AND other folders.
• No collisions: Unlike directory browsers and other global data managers it is not possible for folders and variables to collide, meaning that you can have a variable player next to a folder player without one overwriting the other.

1.3 Storage

All Blackboard data is stored within a single BlackboardData resource file which you can create wherever you like. The path to this resource is saved in Project Settings and loaded automatically.

Note

The editor interface is restricted to creating and editing only the basic types: Int, Float, Bool, and String.
In-game and through manual external editing you can store any serialisable Godot data type (e.g., Arrays, Dictionaries, Vector2, etc.) using the API. These complex values will be displayed by their type name in the editor but cannot be edited visually.

---

II. The Editor Interface

2.1 Folder Hierarchy (Left Panel)

This section manages the top-down organization of the data structure.

• Top-Level Creation: Next to the folder search field, there is a button with a Folder and a Green '+' icon. Clicking this button creates a new top-level folder.
• Folder Item Controls: Each folder item includes two buttons on its right side:
  1. Add Subfolder: A button featuring a Folder with a Green '+' icon. Clicking this creates a new subfolder nested within the current item.
  2. Delete Folder: A Trash Bin icon. Clicking this requires confirmation before recursively deleting the selected folder and all its contents (subfolders and variables).
• Renaming: Folder names can be edited by double-clicking the name in the tree.
• Reordering: You can change a folder's container or location by dragging and dropping it. The order of the folders will be preserved when reopening a project.
• Variable reassignment: You can drag and drop variables on folders to change the containing folder.

Note

Folders can't contain / in the name. This character will be changed to _ when changing a folder's name.

2.2 Variable View (Right Panel)

This section shows the contents of the currently selected folder.

• Creation: The header provides quick-access buttons to create variables of basic types (Int, Float, Bool, String).
• Variable List: Variables are displayed showing their Name and Value (or Type if complex).
• Copy Path Utility: A copy button next to each variable copies its full path (e.g., "player/stats/health") to the clipboard, ready for use in other Nexus Forge tools like Discourse.
• Editing: Variable names and basic type values can be edited by double-click them.
• Sorting: Pressing on a column title will sort the variables based on the column you clicked (by name or type).

Note

Variables can't contain / in the name. This character will be changed to _ when changing a variable's name.

---

III. Usage in GDScript (API Hooks)

The API is accessed via the NexusForge.Blackboard singleton. All functions use String for folder paths and StringName for variable keys for optimised lookups.

3.1 Data Setting and Creation

Note

On any function that takes a folder path, the path will be cleaned using String.simplify_path() in order to make the paths reliable. This means a path like /player/data//health/ will turn into player/data/health.

Function Signature	Purpose	Notes
set_variable(variable_path: String, variable: Variant)	Sets the value of a variable.	If variable is passed as null, the key-value pair is erased to save memory.
create_folder(path: String)	Creates the full folder path structure (e.g., a/b/c).	Skips creation if a folder already exists to prevent data loss.
erase_folder(path: String)	Deletes the specified folder and all its contents recursively.	Use with caution as it erases the folder's variables and its subfolders.
clear()	Clears the entire Blackboard (all folders and variables).

Note

create_folder creates a directory recursively. Meaning that you can create a complete nested folder structure with just one call.

Warning

The function set_variable() expects the "folder" to already exist. Trying to set a variable on an inexistent folder will result in the data not being set and an error printing.

3.2 Data Retrieval

Function Signature	Purpose	Notes
get_variable(variable_path: String, fallback: Variant)	Retrieves the variable value.	Returns fallback if it can't access the variable path.
variables(folder: String)	Returns an Array of all variable keys (StringName) in the folder.
folders(at: String = "")	Returns an Array of all immediate subfolders in the at path.	at defaults to "" (top level).

3.3 Existence Checks

Function Signature	Purpose	Notes
has_variable(variable_path: String)	Checks if the variable exists.
has_folder(path: String)	Checks if the folder path exists.
is_folder_empty(path: String)	Returns true if the folder has no variables, or if the path doesn’t exist.

3.4 Signals

Signal	Purpose	Arguments
data_set	Emits when data was set on the blackboard.	path(String): The path of the variable set.
data_erased	Emits when data was removed from the blackboard.	path(String): The path of the variable removed.
folder_created	Emits when a folder path was created.	path(String): The path of the folder created.
folder_erased	Emitted when a folder is removed.	path(String): The path of the folder removed.