feat: Introduce GUI for live configuration and persistent settings via config.ini, enabling customizable overlay position and fall direction.

Ian-bug · Ian-bug · commit 654bcbe4b7ba · 2025-12-21T22:42:39.000+08:00
diff --git a/.gitignore b/.gitignore
@@ -3,3 +3,4 @@ __pycache__/
 implementation_plan.md
 task.md
 walkthrough.md
+config.ini
diff --git a/README.md b/README.md
@@ -19,6 +19,9 @@ RainingKeys is a purely external overlay application that visualizes keyboard in
 ## Features
 
 - **External Overlay**: Runs as a transparent, always-on-top, click-through window over any game.
+- **Graphic Interface**: Live configuration window to adjust settings on the fly.
+- **Positioning**: Configurable X/Y overlay position.
+- **Fall Direction**: Supports both Down (Classic) and Up (Reverse) fall directions.
 - **Accurate Timing**: Uses high-resolution monotonic clocks (`time.perf_counter`) for smooth, jitter-free falling animation.
 - **Lane System**: Configurable key-to-lane mapping (e.g., WASD, Space, Enter).
 - **Long Press Support**: Visualizes held keys with variable-length bars.
@@ -64,23 +67,30 @@ RainingKeysPython/
     ```bash
     python main.py
     ```
-2.  The overlay will appear (default: full screen transparent window).
-3.  Press the configured keys (Default: `a`, `s`, `l`, `;`) to see the visualization.
-4.  The Debug Overlay in the top-left corner shows FPS and object pool stats.
-5.  **To Exit**: Press `Ctrl+C` in the terminal window.
+2.  **Two windows will appear**:
+    - The transparent **Overlay** (shows the bars).
+    - The **RainingKeys Config** window (controls settings).
+3.  Use the Config window to move the overlay or change speed/direction live.
+4.  Press the configured keys (Default: `a`, `s`, `l`, `;`) to see the visualization.
+5.  **To Exit**: Close the Config window or press `Ctrl+C` in the terminal.
 
 ## Configuration
 
-Edit `core/config.py` to customize the overlay:
+## Configuration
+
+Settings are stored in `config.ini` (automatically created on first run).
+You can edit this file manually or use the **GUI Settings Window**.
+
+### Config Options
+
+| Section | Parameter | Description |
+| :--- | :--- | :--- |
+| `Visual` | `scroll_speed` | Falling speed in pixels per second. |
+| `Visual` | `fall_direction` | `down` or `up`. |
+| `Position` | `x` | Overlay X position (pixels). |
+| `Position` | `y` | Overlay Y position (pixels). |
 
-| Parameter | Description |
-| :--- | :--- |
-| `SCROLL_SPEED` | Falling speed in pixels per second. |
-| `LANE_MAP` | Dictionary mapping specific keys (e.g., `'a'`, `'Key.space'`) to lane indices. |
-| `BAR_WIDTH` | Visual width of the falling notes. |
-| `INPUT_LATENCY_OFFSET` | Seconds to offset rendering (useful for audio sync). |
-| `MAX_BARS` | Soft limit for the object pool (prevents memory leaks). |
-| `COLORS` | RGBA values for bars and text. |
+*Note: Key mappings and colors are currently defined in `core/config.py`.*
 
 ## Roadmap
 
diff --git a/core/gui.py b/core/gui.py
@@ -0,0 +1,76 @@
+from PySide6.QtWidgets import QWidget, QVBoxLayout, QHBoxLayout, QLabel, QSpinBox, QComboBox, QGroupBox
+from PySide6.QtCore import Qt
+from .settings_manager import SettingsManager
+
+class SettingsWindow(QWidget):
+    def __init__(self, settings_manager: SettingsManager):
+        super().__init__()
+        self.settings = settings_manager
+        self.init_ui()
+        self.setWindowTitle("RainingKeys Config")
+        self.resize(300, 250)
+
+    def init_ui(self):
+        layout = QVBoxLayout()
+        
+        # Position Group
+        pos_group = QGroupBox("Overlay Position")
+        pos_layout = QHBoxLayout()
+        
+        self.spin_x = QSpinBox()
+        self.spin_x.setRange(-10000, 10000)
+        self.spin_x.setPrefix("X: ")
+        self.spin_x.setValue(self.settings.overlay_x)
+        self.spin_x.valueChanged.connect(self.on_pos_changed)
+        
+        self.spin_y = QSpinBox()
+        self.spin_y.setRange(-10000, 10000)
+        self.spin_y.setPrefix("Y: ")
+        self.spin_y.setValue(self.settings.overlay_y)
+        self.spin_y.valueChanged.connect(self.on_pos_changed)
+        
+        pos_layout.addWidget(self.spin_x)
+        pos_layout.addWidget(self.spin_y)
+        pos_group.setLayout(pos_layout)
+        layout.addWidget(pos_group)
+        
+        # Visual Group
+        vis_group = QGroupBox("Visual Settings")
+        vis_layout = QVBoxLayout()
+        
+        # Direction
+        dir_layout = QHBoxLayout()
+        dir_layout.addWidget(QLabel("Fall Direction:"))
+        self.combo_dir = QComboBox()
+        self.combo_dir.addItems(["down", "up"])
+        self.combo_dir.setCurrentText(self.settings.fall_direction)
+        self.combo_dir.currentTextChanged.connect(self.on_visual_changed)
+        dir_layout.addWidget(self.combo_dir)
+        vis_layout.addLayout(dir_layout)
+        
+        # Speed
+        speed_layout = QHBoxLayout()
+        speed_layout.addWidget(QLabel("Scroll Speed (px/s):"))
+        self.spin_speed = QSpinBox()
+        self.spin_speed.setRange(100, 5000)
+        self.spin_speed.setSingleStep(50)
+        self.spin_speed.setValue(self.settings.scroll_speed)
+        self.spin_speed.valueChanged.connect(self.on_visual_changed)
+        speed_layout.addWidget(self.spin_speed)
+        vis_layout.addLayout(speed_layout)
+        
+        vis_group.setLayout(vis_layout)
+        layout.addWidget(vis_group)
+        
+        layout.addStretch()
+        self.setLayout(layout)
+
+    def on_pos_changed(self):
+        self.settings.set('Position', 'x', self.spin_x.value())
+        self.settings.set('Position', 'y', self.spin_y.value())
+        self.settings.save() 
+        
+    def on_visual_changed(self):
+        self.settings.set('Visual', 'fall_direction', self.combo_dir.currentText())
+        self.settings.set('Visual', 'scroll_speed', self.spin_speed.value())
+        self.settings.save()
diff --git a/core/overlay.py b/core/overlay.py
@@ -47,23 +47,11 @@ def spawn(self, lane_index, timestamp):
         if self.inactive_bars:
             bar = self.inactive_bars.pop()
         else:
-            # Pool exhausted.
-            # Strategy: If below max_size, create new.
-            # If at max_size, recycle the oldest active bar (soft limit).
-            total_count = len(self.active_bars) + len(self.inactive_bars) # logic check
-            # Actually total known count is just what we have tracked.
-            # Let's track total instantiated count if strictly needed, 
-            # but deque length is good enough.
-            
-            # Simple count check:
             if (len(self.active_bars) + len(self.inactive_bars)) < self.max_size:
                 bar = Bar()
             elif self.active_bars:
-                # Soft Limit hit: Recycle oldest
-                bar = self.active_bars.popleft() # Oldest is usually at the left/start
-                # Technically we are taking it out of active to re-add it as new active
+                bar = self.active_bars.popleft()
             else:
-                # Should effectively never happen unless max_size=0
                 bar = Bar() 
         
         bar.active = True
@@ -79,16 +67,21 @@ def recycle(self, bar):
         self.inactive_bars.append(bar)
 
 class RainingKeysOverlay(QWidget):
-    def __init__(self):
+    def __init__(self, settings_manager):
         super().__init__()
-        self.init_ui()
+        self.settings = settings_manager
+        # Connect to settings changed signal
+        self.settings.settings_changed.connect(self.on_settings_changed)
+        
         self.pool = BarPool(Config.MAX_BARS)
         self.active_holds = {} # {lane_index: Bar} tracking currently held notes
         
+        self.init_ui()
+        
         # High-res timer for rendering
         self.timer = QTimer(self)
         self.timer.timeout.connect(self.update_canvas)
-        self.timer.start(16) # ~60 FPS target trigger, but delta used for physics
+        self.timer.start(16) # ~60 FPS target trigger
 
         # Debug stats
         self.last_fps_time = time.perf_counter()
@@ -100,26 +93,42 @@ def init_ui(self):
         self.setWindowFlags(
             Qt.FramelessWindowHint | 
             Qt.WindowStaysOnTopHint | 
-            Qt.Tool | # Tool prevents showing in alt-tab usually
-            Qt.WindowTransparentForInput # Qt 5.10+ helper, acts as partial clickthrough
+            Qt.Tool | 
+            Qt.WindowTransparentForInput
         )
         self.setAttribute(Qt.WA_TranslucentBackground)
         self.setAttribute(Qt.WA_TransparentForMouseEvents)
 
-        # Full screen
-        screen_geo = QApplication.primaryScreen().geometry()
-        self.setGeometry(screen_geo)
+        # Initial calculation for window size
+        # We need enough width for all lanes
+        max_lane = 0
+        if Config.LANE_MAP:
+             max_lane = max(Config.LANE_MAP.values())
+        
+        # Width: Start Offset + (Max Lane Index + 1) * Lane Width + Extra Padding
+        width = Config.LANE_START_X + ((max_lane + 1) * Config.LANE_WIDTH) + 50
+        height = QApplication.primaryScreen().size().height()
+        
+        self.resize(width, height)
+        # Move to configured position
+        self.move(self.settings.overlay_x, self.settings.overlay_y)
 
-        # Win32 Click-through + Always on Top enforcement
+        # Win32 Click-through
         if HAS_WIN32:
             hwnd = int(self.winId())
-            styles = win32gui.GetWindowLong(hwnd, win32con.GWL_EXSTYLE)
-            win32gui.SetWindowLong(hwnd, win32con.GWL_EXSTYLE, styles | win32con.WS_EX_LAYERED | win32con.WS_EX_TRANSPARENT)
+            try:
+                styles = win32gui.GetWindowLong(hwnd, win32con.GWL_EXSTYLE)
+                win32gui.SetWindowLong(hwnd, win32con.GWL_EXSTYLE, styles | win32con.WS_EX_LAYERED | win32con.WS_EX_TRANSPARENT)
+            except Exception as e:
+                print(f"Win32 Error: {e}")
+
+    def on_settings_changed(self):
+        # Move window live when settings change
+        self.move(self.settings.overlay_x, self.settings.overlay_y)
 
     def handle_input(self, lane_index, timestamp):
         """Slot called when input monitor detects a key press."""
         if lane_index in self.active_holds:
-            # Key already held? (Should be filtered by input_mon, but safety check)
             pass
         else:
             bar = self.pool.spawn(lane_index, timestamp)
@@ -138,66 +147,88 @@ def paintEvent(self, event):
         painter = QPainter()
         try:
             if not painter.begin(self):
-                # Failed to start painting (device occupied?)
                 return
             
             painter.setRenderHint(QPainter.Antialiasing)
 
             current_time = time.perf_counter()
-            
-            # Calculate Logic
             screen_h = self.height()
             to_recycle = []
             
+            # Get current settings
+            speed = self.settings.scroll_speed
+            falling_down = (self.settings.fall_direction == 'down')
+
             # Bar Drawing Loop
             for bar in self.pool.active_bars:
-                # Calculate Y positions
-                # Bottom of the note (Leading Edge)
+                # 1. Physics: Distance from Origin (Press Time)
                 delta_press = current_time - bar.press_time + Config.INPUT_LATENCY_OFFSET
-                y_bottom = delta_press * Config.SCROLL_SPEED
+                dist_head = delta_press * speed
                 
-                # Top of the note (Trailing Edge)
                 if bar.release_time is None:
-                    # Still held: Top is at current time (0 offset from 'now')
-                    delta_release = Config.INPUT_LATENCY_OFFSET # effectively 0 time passed since 'now'
-                    y_top = delta_release * Config.SCROLL_SPEED
+                    # Held
+                    dist_tail = Config.INPUT_LATENCY_OFFSET * speed
                 else:
+                    # Released
                     delta_release = current_time - bar.release_time + Config.INPUT_LATENCY_OFFSET
-                    y_top = delta_release * Config.SCROLL_SPEED
+                    dist_tail = delta_release * speed
 
-                # Check bounds (Recycle if Top is off-screen)
-                if y_top > screen_h:
-                    to_recycle.append(bar)
-                    continue
+                # 2. Geometry
+                height_bar = dist_head - dist_tail
+                # Clamp min height so short taps are visible
+                if height_bar < Config.BAR_HEIGHT:
+                     height_bar = Config.BAR_HEIGHT
+                     dist_tail = dist_head - height_bar
                 
-                # Render only if VISIBLE
-                if y_bottom < 0:
-                     continue
-
-                # Fade Logic (based on leading edge / y_bottom)
+                # Calculate Screen Y
+                if falling_down:
+                    # Spawn at 0 (Top)
+                    # Tail is "above" Head (smaller Y value)
+                    rect_y = dist_tail
+                else:
+                    # Spawn at ScreenHeight (Bottom)
+                    # Head moves UP (smaller Y value)
+                    # Tail moves UP (larger Y value than Head)
+                    # Y = H - dist. 
+                    # Head Y = H - dist_head.
+                    # Tail Y = H - dist_tail.
+                    # Rect Top = Head Y (Smallest Y)
+                    rect_y = screen_h - dist_head
+                
+                # 3. Recycle Check
+                if falling_down:
+                    if rect_y > screen_h:
+                        to_recycle.append(bar)
+                        continue
+                else:
+                    # Moving Up. If the bottom of that rect (rect_y + height) is < 0, it is gone.
+                    if (rect_y + height_bar) < 0:
+                        to_recycle.append(bar)
+                        continue
+                
+                # 4. Fade Logic (Distance Traveled based)
+                # Use dist_head (leading edge travel distance)
                 alpha = 1.0
-                if y_bottom > Config.FADE_START_Y:
-                    dist_into_fade = y_bottom - Config.FADE_START_Y
+                if dist_head > Config.FADE_START_Y:
+                    dist_into_fade = dist_head - Config.FADE_START_Y
                     factor = 1.0 - (dist_into_fade / Config.FADE_RANGE)
                     alpha = max(0.0, min(1.0, factor))
-                
-                # Draw
+
+                # 5. Draw
+                # Optimization: Don't draw if transparent
+                if alpha <= 0.0:
+                    continue
+                    
                 x = Config.LANE_START_X + (bar.lane_index * Config.LANE_WIDTH)
                 
-                # Height
-                h = max(Config.BAR_HEIGHT, y_bottom - y_top)
-                
-                draw_y = y_bottom - h
-                
-                # Apply Color
                 c = QColor(Config.COLOR_BAR)
                 c.setAlphaF(alpha * (Config.COLOR_BAR.alphaF())) 
                 
                 painter.setBrush(QBrush(c))
                 painter.setPen(Qt.NoPen)
-                painter.drawRect(QRectF(x, draw_y, Config.BAR_WIDTH, h))
+                painter.drawRect(QRectF(x, rect_y, Config.BAR_WIDTH, height_bar))
 
-            # Recycle off-screen bars
+            # Recycle
             for bar in to_recycle:
                 try:
                     self.pool.active_bars.remove(bar)
@@ -230,9 +261,11 @@ def draw_debug(self, painter, current_time):
         
         info = [
             f"FPS: {self.current_fps:.1f}",
-            f"Active Bars: {active_count} / {Config.MAX_BARS}",
-            f"Pool Size: {pool_size}",
-            f"Speed: {Config.SCROLL_SPEED} px/s"
+            f"Active: {active_count}",
+            f"Pool: {pool_size}",
+            f"Speed: {self.settings.scroll_speed}",
+            f"Dir: {self.settings.fall_direction}",
+            f"Pos: {self.x()},{self.y()}"
         ]
         
         for i, line in enumerate(info):
diff --git a/core/settings_manager.py b/core/settings_manager.py
diff --git a/main.py b/main.py
