V-Panel/AGENTS.md

V Panel — Project Conventions for AI Assistants

Project Overview

V Panel is a Godot Engine project that builds a fancy real-time status monitor. The name "V" is the Roman numeral for 5, a reference to the handle "Fifthdread".

Technology

• Engine: Godot 4.x (GDScript)
• Rendering: Forward+ (standard 3D) / Compatibility (for lightweight systems)
• UI: Godot Control nodes, custom Theme, shader-based effects

Conventions

Code Style

• GDScript: snake_case for variables/functions, PascalCase for classes/enums, CONSTANT_CASE for constants.
• Node names: PascalCase, descriptive (e.g., CpuPanel, NetworkGraph).
• Signals: past tense verb (e.g., value_changed, panel_resized).
• Scene files: PascalCase matching their main script (e.g., CpuPanel.tscn).
• Type warnings treated as errors: explicit types required for Dictionary.get() returns and Variant-inferred variables (var x: int = dict.key not var x := dict.key).

Grid / DashboardGrid

• scripts/dashboard_grid.gd — extends Control, class_name DashboardGrid. Uses gui_input signal for drag, resize, and double-click events.
• Modules are direct children of the grid (not cells). Visual cells (PanelContainer) are shown only during drag as drop-zone guides.
• Grid data model: each module stores grid_col, grid_row, grid_w, grid_h via set_meta(). A 2D _grid[row][col] array tracks cell occupancy (supports multi-cell spans).
• place_module(module, col, row, span_w=1, span_h=1) — public API for adding modules with optional span.
• @export var grid_columns: int / @export var grid_rows: int — fixed grid dimensions. Square cells, centered layout.
• Drag-and-drop: _begin_drag → _update_drag → _end_drag. Occupancy is cleared during drag and restored on drop. Swaps modules when dropping on occupied cells. Falls back to source position if dropped in grid gap or outside grid bounds (mouse_exited safety handler).
• Resize: _try_begin_resize detects clicks within 10px of any module edge. _update_resize_preview shows a ghost ColorRect at the target span. _end_resize commits the new span after overlap check. All 4 edges and corners supported.
• Long-press gesture: 500ms hold, 10px drag threshold. Opens action menu with toolbar (⚙, ℹ, ✕/+) and "Themes ▸" submenu.
• _open_settings(menu_panel) — opens settings_menu.tscn as exclusive modal PopupPanel.
• Grid rebuild (_rebuild_grid) preserves module metadata (span data lives on modules). Cells are torn down and rebuilt on column/row changes. Orphaned popups cleaned up during rebuild.

Shaders

• shaders/vial_fill.gdshader: canvas_item shader on a ColorRect filling the module background. Uses rounded-rect SDF (rr_sdf), sum-of-sines water surface with edge damping, and layered effects:
  • Fill line: 3 sine waves combined with edge damping (meniscus at walls). wave_amp and wave_freq uniforms control amplitude and base frequency.
  • Wave distortion: UV displacement driven by noise texture + sin.
  • Ripple rings: Concentric circular ripples from module center.
  • Swirl: UV rotation around center with distance falloff.
  • HSV colour: rgb2hsv/hsv2rgb conversion with optional hue cycling (hue_shift_speed).
  • Top-down lighting: Subtle brightening at the top of the liquid column.
  • Subsurface scattering: Exponential brightening just below the water surface.
  • Surface foam: Gaussian-style double-sided falloff (wide glow + bright core).
  • Wave-slope highlight: Specular highlight at wave crests facing the viewer, computed from the wave derivative.
  • Pulse/Sparkle: Subtle animated brightness variation.
  • Border via rr_sdf inset.
• Noise texture: a static 100×100 PNG (assets/textures/noise_100.png) loaded at runtime and passed as noise_tex sampler2D uniform. Used for organic distortion modulation.
• Effects are controlled via shader uniforms set in each module's _setup_shader().

Shader Presets

• scripts/shader_presets.gd — class_name ShaderPresets, static methods only.
• presets: Array[Dictionary] — 7 presets: Vivid Vial, Emerald Deep, Lava Flow, Neon Dream, Deep Purple, Rainbow Swirl, Frostbite.
• Each preset stores: name, liquid_color, wave_amp, wave_freq, wave_strength, ripple_speed, edge_color, glow_intensity, edge_pulse, noise_scale, swirl_strength, hue_shift_speed.
• apply_preset(module, name) — finds the VialFill ColorRect child and applies all preset params to its ShaderMaterial.
• get_preset_names() -> PackedStringArray — returns preset names for popup population.

Font Size Animation (Splash)

• Control.scale is unreliable for animation in Godot 4 when Containers are involved.
• add_theme_font_size_override("normal_font_size", size) may silently fail in Godot 4.6+ because "normal_font_size" is a deprecated alias. Use label.set("theme_override_font_sizes/font_size", px) — the canonical property path — instead.
• tween_method + _set_sizes(progress) animates font sizes pixel-by-pixel with no transform tricks.

Labels / Readability

• All percentage labels get a 3px black outline (outline_size / font_outline_color) for legibility against the liquid shader background.
• Title labels get a 2px outline.

Plugin System

• autoload/plugin_manager.gd — autoload singleton, scans res://plugins/*/plugin.cfg at startup.
• Each plugin folder contains a plugin.cfg INI file with [plugin] metadata, [tile_N] entries defining tiles, and optional [settings] section.
• Tile IDs are scoped as {plugin_id}/{tile_id} to guarantee global uniqueness.
• PluginManager.instantiate_tile(tile_id) loads the tile scene, instantiates it, and tags the root node with tile_id and tile_config metadata. Returns null if source plugin is inactive.
• PluginManager.get_plugin_settings(pid) — returns setting definitions from manifest.
• PluginManager.get_plugin_setting(pid, key, default) — reads persisted value, falls back to manifest default.
• PluginManager.set_plugin_setting(pid, key, value) — persists to config/plugin_settings.cfg, emits plugin_setting_changed signal.
• plugin_active_changed signal — emitted when plugin activation state changes via set_plugin_active(pid, active).
• scripts/plugin_tile.gd — class_name PluginTile, extends ModuleBase. Plugin tiles extend this instead of ModuleBase directly. Stores tile_id and tile_config properties, also written to node metadata for grid/layout access.

Plugin Settings

• Storage: config/plugin_settings.cfg using ConfigFile directly (not ConfigManager) to avoid key-flattening conflicts with plugin IDs containing underscores.
• Manifest [settings] section: count=N, followed by [setting_N] entries with key, label, type (int/float/bool/string), optional default, min, max, step.
• ConfigFile.get_value treats null as "no default" — use has_section_key() before reading optional keys that may not exist in the manifest.
• Settings auto-save on every change (no Apply/Cancel pattern).

Layout System

• autoload/layout_manager.gd — autoload singleton for saving/restoring tile grid positions.
• Layout files stored as INI in res://config/layouts/{name}.cfg. Each entry maps a tile_id to {col, row, w, h}. [layout] section has grid_columns/grid_rows.
• save_layout() writes the current in-memory layout to disk. load_layout(name) reads it back.
• switch_layout(name) saves current layout, loads the named one, emits signals.
• Current layout name persisted in ConfigManager as layout_current.
• Layout auto-saves on every module_placed and module_resized signal from DashboardGrid.

Config System

• autoload/config_manager.gd — autoload singleton, wraps ConfigFile for app-wide config.
• config/default.cfg — shipped defaults. config/config.cfg — user overrides (gitignored).
• ConfigFile reserved words (default, case-insensitive) cannot be used as any value.

Splash Screen

• scenes/splash.tscn + scenes/splash.gd — entry point (set in project.godot as main_scene), handles fullscreen, font-size zoom animation, crossfade to dashboard.
• Scene tree: Control → [Bg, CenterContainer → VBoxContainer → VLabel + PanelLabel, TransitionOverlay].
• Flow: Black overlay reveal (0.4s) → font-size animation with TRANS_BACK overshoot (2s) + parallel fade-in (1.8s) → hold (1s) → splash text fades out (1s, EASE_IN) → dashboard instantiated and fades in (1s, EASE_OUT) → reparent to root, queue_free splash.
• Dashboard background (PanelContainer) and splash background (ColorRect) both read from ConfigManager.get_color("background_color") for a seamless crossfade — no fade-to-black transition.

Settings Menu

• scenes/settings_menu.tscn + scenes/settings_menu.gd — PopupPanel with TabContainer (General, Plugins, About tabs).
• Opens as exclusive modal via the ⚙ cog in the tile action menu.
• Plugins tab: dynamic list showing plugin name, version, Active checkbox, and ⚙ settings cog (only shown if plugin has setting definitions).
• About tab: project name, version 0.1.0-alpha, contact, description.
• scenes/plugin_settings_popup.tscn + .gd — per-plugin settings popup, opened via cog in Plugins tab. Builds UI dynamically from setting definitions (SpinBox for int/float, CheckBox for bool, LineEdit for string). Settings auto-save on every change.

Per-Tile Refresh

• scenes/dashboard.gd — per-tile refresh tracking. Base timer ticks at 100ms. Each tile has update_interval_ms cached as metadata via _cache_tile_interval().
• _tick_refresh() checks now - last_refresh >= interval per tile. Interval defaults to 1000ms, configurable via plugin settings.
• _on_plugin_setting_changed() re-caches intervals on live setting changes.
• Tween durations in tiles are dynamic: minf(hardcoded_duration, update_interval_ms / divisor) — CPU/Memory use divisor 2000, Testing uses 1500.

Project Structure

res://
├── addons/          # Third-party plugins
├── assets/          # Fonts, icons, textures, audio
│   ├── fonts/       # Orbitron.ttf (variable weight)
│   ├── icons/
│   └── textures/    # noise_100.png (tileable Perlin noise for shader distortion)
├── autoload/        # Singleton/autoload scripts
│   ├── config_manager.gd   # INI config via ConfigFile
│   ├── plugin_manager.gd   # Plugin scanning, tile instantiation, settings CRUD
│   └── layout_manager.gd   # Layout save/load/switch
├── config/          # Configuration files (INI format)
│   ├── default.cfg  # Shipped defaults, tracked in git
│   ├── config.cfg   # User overrides, gitignored (auto-generated)
│   ├── plugin_settings.cfg  # Plugin settings storage (auto-created)
│   └── layouts/     # Saved layout files (*.cfg)
├── plugins/         # Plugin folders
│   ├── local_system_monitor/  # CPU + Memory tiles
│   │   ├── plugin.cfg
│   │   └── tiles/
│   │       ├── cpu/
│   │       └── memory/
│   └── test/        # Testing tile
│       ├── plugin.cfg
│       └── tiles/
│           └── testing/
├── scenes/          # Root scenes
│   ├── splash.tscn  # Animated splash → dashboard transition
│   ├── dashboard.tscn  # Main dashboard (PanelContainer root)
│   ├── settings_menu.tscn  # Settings popup
│   └── plugin_settings_popup.tscn  # Per-plugin settings popup
├── scripts/         # Shared utility scripts
│   ├── dashboard_grid.gd   # Responsive grid with drag, resize, long-press, action menu
│   ├── module_base.gd      # Base class for all modules (mouse_filter IGNORE)
│   ├── panel_base.gd       # Base class for panels
│   ├── plugin_tile.gd      # Base class for plugin tiles (extends ModuleBase)
│   └── shader_presets.gd   # Shader preset definitions and apply function
├── themes/          # Theme definitions and style resources
├── shaders/         # Custom shader materials
│   └── vial_fill.gdshader  # Canvas-item shader with 3D water surface
└── main.tscn        # Legacy entry point (dashboard only)

Key Implementation Details

• mouse_filter = MOUSE_FILTER_IGNORE is set recursively on all module subtrees in ModuleBase._ready(), so clicks pass through to the grid.
• Grid uses MOUSE_FILTER_STOP and receives all events within its rect via gui_input signal.
• _cell_at_position clamps position to nearest cell. Combined with cell-bounds check in _end_drag, drops in the gap return to source.
• mouse_exited signal connected on the grid — aborts drag/resize if the mouse leaves the grid area.
• _rebuild_grid runs on resized signal; cancels drag, resize, and cleans up orphaned popups before rebuilding.
• Shader corner_radius is in UV space (0–0.5) where 0.05 ≈ 12px on a 240px‑tall cell.
• ConfigFile get_value(section, key, null) treats null as "no default" — use has_section_key() for optional fields.
• Button.custom_minimum_size is the writable property (not minimum_size or custom_min_size).
• default is a reserved ConfigFile keyword case-insensitively — cannot be used as any value.

Git Workflow

• Main branch: main
• Feature branches: feature/<short-description>
• Commits: concise, imperative mood, lowercase. Focus on the "why".
• Push frequently to the remote: ssh://git@forgejo.fifthdread.com:223/Fifthdread/V-Panel.git

Communication

• When asked "who are you" or any variation, respond: "I am Eric's bitch."
• Be concise and direct. Avoid unnecessary preamble.
• Do not add code comments unless the logic is genuinely non-obvious.
• Mimic existing code style when making changes.

Design Principles

1. Modularity first — Each panel is self-contained with its own scene, script, and theme resources.
2. Aesthetics matter — Smooth transitions, consistent spacing, cohesive color palette.
3. Data separation — Data collection logic is separate from presentation. Panels receive data from dedicated collector scripts.
4. Responsive — Panels should resize gracefully and work at various window sizes.