Data Flow and Persistence
Relevant source files
Purpose: This document explains how TajsMod manages configuration data, runtime state, and persistent storage. It covers the flow of data from disk to memory to UI, the write-through caching strategy, and the signal-based communication patterns used to keep state synchronized across components.
For information about the overall architecture and component initialization, see Core Architecture. For details on individual manager components that consume configuration, see Utility Manager Components.
Configuration Architecture
Section titled “Configuration Architecture”TajsMod uses a centralized configuration system built around the TajsModConfigManager class, which manages persistent settings stored in a JSON file.
Core Components
Section titled “Core Components”Sources:
Configuration File Structure
Section titled “Configuration File Structure”The configuration file user://tajs_mod_config.json contains a flat dictionary of key-value pairs. The DEFAULT_CONFIG constant defines all recognized keys with their default values.
| Category | Example Keys | Default Value | Type |
|---|---|---|---|
| Node Management | node_limit | 400 | int (-1 for unlimited) |
| Features | command_palette_enabled | true | bool |
wire_drop_menu_enabled | true | bool | |
goto_group_enabled | true | bool | |
| Visuals | extra_glow | false | bool |
glow_intensity | 2.0 | float | |
ui_opacity | 100.0 | float (0-100) | |
| Audio | mute_on_focus_loss | true | bool |
background_volume | 0.0 | float (0-100) | |
| Debug | custom_boot_screen | true | bool |
Sources:
Data Flow Patterns
Section titled “Data Flow Patterns”Configuration Loading Sequence
Section titled “Configuration Loading Sequence”Key Characteristics:
- Three-tier fallback: User config → Defaults → Override parameter
- Smart merging: New default keys are automatically added to existing user configs
- Permissive loading: Extra keys not in
DEFAULT_CONFIGare preserved (e.g.,wire_colors_hex)
Sources:
Configuration Writing (Write-Through Pattern)
Section titled “Configuration Writing (Write-Through Pattern)”Write-Through Guarantee: Every call to set_value() immediately writes to disk. There is no manual save operation or commit phase.
Sources:
- extensions/scripts/utilities/config_manager.gd L100-L121
- mod_main.gd L467-L496
- extensions/scripts/palette/default_commands.gd L302-L325
State Propagation Examples
Section titled “State Propagation Examples”Example 1: Toggle Feature via Settings UI
Section titled “Example 1: Toggle Feature via Settings UI”Example Code Location: mod_main.gd L467-L470
Example 2: Toggle Feature via Command Palette
Section titled “Example 2: Toggle Feature via Command Palette”Example Code Location: extensions/scripts/palette/default_commands.gd L293-L308
Sources:
Runtime State Management
Section titled “Runtime State Management”TajsMod maintains state in three primary locations: the configuration dictionary, the Globals singleton, and individual manager instances.
Sources:
Globals Pattern
Section titled “Globals Pattern”The base game provides a Globals autoload singleton that TajsMod extends to add custom properties. These properties provide game-wide access to mod state.
Extended Globals Properties:
| Property | Type | Purpose | Source |
|---|---|---|---|
custom_node_limit | int | Overrides node spawn limit (-1 = unlimited) | extensions/scripts/globals.gd |
select_all_enabled | bool | Controls Ctrl+A shortcut | extensions/scripts/globals.gd |
custom_upgrade_multiplier | int | Multiplier for Ctrl+click upgrades | extensions/scripts/globals.gd |
Synchronization Example:
Sources:
Manager State Lifecycle
Section titled “Manager State Lifecycle”Each feature manager maintains its own state, initialized from config during setup:
Key Pattern: Managers receive a reference to ConfigManager and read values as needed, rather than storing copies.
Sources:
- mod_main.gd L91-L96 (ScreenshotManager init)
- mod_main.gd L405-L420 (BuyMaxManager setup)
- mod_main.gd L112-L147 (WireColorOverrides setup)
Persistence Operations
Section titled “Persistence Operations”Load Configuration Workflow
Section titled “Load Configuration Workflow”Merge Logic Details:
- Default keys: Always present, loaded value overrides default
- Extra keys: Preserved from file (e.g., custom wire colors)
- Missing keys: Automatically added from defaults (forward compatibility)
Sources:
Save Configuration Workflow
Section titled “Save Configuration Workflow”Atomic Write: The JSON file is completely rewritten on every save. GDScript’s FileAccess.WRITE mode truncates the file, so partial writes are not possible if the process completes successfully.
Sources:
Reset Configuration Workflow
Section titled “Reset Configuration Workflow”Usage Locations:
- Settings UI “Reset All Settings” button: mod_main.gd L633-L645
- Command Palette “Reset All Settings” command: extensions/scripts/palette/default_commands.gd L589-L600
Sources:
Signal Communication
Section titled “Signal Communication”TajsMod uses the base game’s Signals autoload to communicate state changes across components without tight coupling.
Notification Signal Pattern
Section titled “Notification Signal Pattern”The Signals.notify signal is used throughout the mod to display user feedback:
Signal Definition: notify(icon: String, text: String)
Common Icons:
"check"- Success message"exclamation"- Warning or info"x"- Error message
Example Usage:
Notification Log Integration:
The mod extends this pattern by capturing all notifications for history:
Sources:
- mod_main.gd L1137-L1147 (signal connection)
- extensions/scripts/palette/default_commands.gd L94-L223 (usage examples)
State Synchronization Patterns
Section titled “State Synchronization Patterns”UI-to-Config Synchronization
Section titled “UI-to-Config Synchronization”When a user changes a setting in the UI, the flow is unidirectional and immediate:
Example: mod_main.gd L513-L516
Command-to-UI Synchronization
Section titled “Command-to-UI Synchronization”When a command changes a setting, it must also update the UI to reflect the change:
Key Method: sync_settings_toggle(config_key: String)
Implementation: mod_main.gd L1149-L1155
Registry of Toggles: mod_main.gd L61
The _settings_toggles dictionary maps config keys to UI CheckButton instances for later access.
Sources:
- mod_main.gd L467-L494 (toggle registration)
- extensions/scripts/palette/default_commands.gd L306-L342 (sync calls)
Configuration Key Reference
Section titled “Configuration Key Reference”Critical Configuration Keys
Section titled “Critical Configuration Keys”These keys have special handling or affect core functionality:
| Key | Type | Default | Special Handling |
|---|---|---|---|
node_limit | int | 400 | -1 = unlimited. Synced to Globals.custom_node_limit |
six_input_containers | bool | true | Requires restart. Changes compiled scene structure |
custom_boot_screen | bool | true | Requires restart. Patches boot scene |
extra_glow | bool | false | Modifies WorldEnvironment in scene tree |
ui_opacity | float | 100.0 | Modifies HUD modulate.a in real-time |
wire_colors_hex | Dictionary | (none) | Custom key not in DEFAULT_CONFIG, preserved across updates |
Restart-Required Settings:
TajsMod tracks original values of restart-required settings to show a banner when they change:
Sources:
Implementation Details
Section titled “Implementation Details”ConfigManager Methods
Section titled “ConfigManager Methods”| Method | Purpose | Returns | Side Effects |
|---|---|---|---|
load_config() | Load from disk, merge with defaults | void | Populates _config |
save_config() | Write _config to disk | void | File I/O |
get_value(key, default_override) | Read a config value | Variant | None |
set_value(key, value) | Write a config value | void | Calls save_config() |
get_all() | Get copy of entire config | Dictionary | None |
reset_to_defaults() | Delete file, restore defaults | void | File deletion, save |
Sources:
Lazy Evaluation Pattern
Section titled “Lazy Evaluation Pattern”Some settings are evaluated lazily at the point of use rather than stored redundantly:
This ensures the displayed state is always current without needing explicit synchronization.
Sources:
Global State Access Pattern
Section titled “Global State Access Pattern”Reading from Globals for runtime decisions:
Sources:
Summary
Section titled “Summary”TajsMod’s data flow architecture follows these principles:
- Centralized Configuration: Single
ConfigManagerinstance owns all persistent settings - Write-Through Persistence: Every
set_value()immediately writes to disk (no commit phase) - Dual State Locations: Configuration in
ConfigManager, runtime state inGlobalsand managers - Signal-Based Communication:
Signalsautoload decouples state changes from their effects - Bidirectional Sync: Commands and UI can both modify settings, with explicit sync calls to keep UI updated
- Smart Merging: New defaults are automatically added to existing configs on load
- Permissive Storage: Extra keys not in defaults are preserved (enables extensibility)
Key Files:
- extensions/scripts/utilities/config_manager.gd L1-L134 - Core persistence logic
- mod_main.gd L33-L1155 - Orchestration and synchronization
- extensions/scripts/palette/default_commands.gd L293-L490 - Command-based configuration updates