From 9adba9d6c2a0895427b83fdef1800adf130435ab Mon Sep 17 00:00:00 2001 From: Eric Smith <5d@fifthdread.com> Date: Wed, 20 May 2026 16:20:58 -0400 Subject: [PATCH] update project docs with grid rewrite, 3d shader, preset system, and key implementation details --- AGENTS.md | 46 ++++++++++++++++++++++++++++++++++++++++++++-- README.md | 12 ++++++++++-- 2 files changed, 54 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a251bff..c805e80 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,12 +17,41 @@ V Panel is a Godot Engine project that builds a fancy real-time status monitor. - 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. +- 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. +- Double-click: opens `PopupMenu` with shader preset names from `ShaderPresets`. Selection applies all preset params to the module's `ShaderMaterial`. +- 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 -- `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 (wave distortion, ripple rings, swirl, HSV shift, top-down lighting, sparkle, foam line). +- `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. + ### 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. @@ -34,7 +63,7 @@ res:// ├── assets/ # Fonts, icons, textures, audio │ ├── fonts/ │ ├── icons/ -│ └── textures/ +│ └── textures/ # noise_100.png (static noise for shader distortion) ├── autoload/ # Singleton/autoload scripts ├── panels/ # Individual status panels (modules) │ ├── cpu/ @@ -44,11 +73,24 @@ res:// │ └── testing/ ├── scenes/ # Root scenes (dashboard, etc.) ├── scripts/ # Shared utility scripts +│ ├── dashboard_grid.gd # Responsive grid with drag, resize, preset popup +│ ├── module_base.gd # Base class for all modules (mouse_filter IGNORE) +│ ├── panel_base.gd # Base class for panels +│ └── 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 # Entry point (loads dashboard) ``` +### 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. + ### Git Workflow - Main branch: `main` - Feature branches: `feature/` diff --git a/README.md b/README.md index e40a62f..201b153 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,9 @@ V Panel is a visually rich, real-time status monitoring dashboard built entirely ## Features - **Responsive grid dashboard** — Modules auto-arrange in a dynamic grid that adapts to window size. Drag-and-drop to rearrange. -- **Shader-based vial fill** — Each module uses a custom `vial_fill.gdshader` instead of progress bars. Features sum-of-sines water surface animation, edge-damped meniscus, wave distortion, ripple rings, swirl, HSV colour shifting, top-down lighting, sparkle effects, and a foam surface line. +- **Variable-size modules** — Modules can span multiple grid cells (1×1, 2×1, 2×2, etc.). Drag edges/corners to resize interactively. +- **Shader-based vial fill** — Each module uses a custom `vial_fill.gdshader` instead of progress bars. Features sum-of-sines water surface with edge-damped meniscus, wave distortion, ripple rings, swirl, HSV colour shifting, top-down lighting, sparkle effects, 3D subsurface scattering, gaussian surface foam, and wave-slope specular highlights. +- **Shader preset system** — Double-click any module to open a popup menu with 7 visual presets (Vivid Vial, Emerald Deep, Lava Flow, Neon Dream, Deep Purple, Rainbow Swirl, Frostbite). Presets control all visual shader parameters. - **Live system monitoring** — Reads CPU usage from `/proc/stat` and memory usage from `/proc/meminfo` on Linux. Extensible module system for adding new collectors. - **Smooth animations** — All fill level transitions use tweens with cubic easing. @@ -21,9 +23,15 @@ V Panel is a visually rich, real-time status monitoring dashboard built entirely | Memory | `/proc/meminfo` | Real-time memory usage percentage | | Testing | N/A (cycles 0–100%) | Shader visual testing with stepped fill levels | +## Controls + +- **Drag module** — Click and drag to rearrange modules on the grid +- **Resize module** — Click and drag any edge or corner to resize (snaps to cell grid) +- **Shader presets** — Double-click a module to open the preset selection popup + ## Project Status -Active development. Core framework, drag-and-drop, CPU/memory collectors, and shader-based vial fill are implemented. More system modules (disk, network) are planned. +Active development. Core framework, drag-and-drop with resize, CPU/memory collectors, shader-based vial fill with 3D surface effects, and preset system are implemented. More system modules (disk, network) are planned. ## License