Initial commit: RainingKeys core implementation

Author: Ian-bug

.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+implementation_plan.md
+task.md
+walkthrough.md

README.md

@@ -0,0 +1,91 @@
+# RainingKeys (Python)
+
+**A high-performance, external rhythm game input visualizer.**
+
+RainingKeys is a purely external overlay application that visualizes keyboard inputs as falling bars, similar to the "Rain" mode found in various rhythm game mods. It provides visual feedback on rhythm stability, micro-jitter, and input timing without injecting code into the game process.
+
+> [!NOTE]
+> This project is a **standalone external tool**. It is **NOT** a game mod and does **NOT** perform DLL injection or memory hooking. It is safe to use with anti-cheat software that permits external overlays.
+
+---
+
+## Features
+
+- **External Overlay**: Runs as a transparent, always-on-top, click-through window over any game.
+- **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.
+- **Performance Optimized**: Implements object pooling and efficient rendering logic to minimize CPU/GPU usage.
+- **Fade Out**: Distance-based fade-out for visual clarity.
+- **Input Latency Compensation**: Configurable offset to visually align inputs with audio latency.
+
+## Tech Stack
+
+- **Python 3.10+**
+- **PySide6 (Qt)**: High-performance rendering and window management.
+- **pynput**: Global low-level keyboard hook.
+- **pywin32**: Windows API integration for transparency and click-through flags.
+
+## Project Structure
+
+```
+RainingKeysPython/
+├── core/
+│   ├── config.py       # User configuration (Keys, speeds, colors)
+│   ├── input_mon.py    # Global input listener
+│   └── overlay.py      # Main rendering loop and window logic
+├── main.py             # Application entry point
+└── requirements.txt    # Dependencies
+```
+
+## Installation
+
+1.  **Prerequisites**: Ensure you have Python 3.10 or newer installed.
+2.  **Clone the repository** (or download source):
+    ```bash
+    git clone https://github.com/your-username/RainingKeysPython.git
+    cd RainingKeysPython
+    ```
+3.  **Install dependencies**:
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+## Usage
+
+1.  Run the application:
+    ```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.
+
+## Configuration
+
+Edit `core/config.py` to customize the overlay:
+
+| 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. |
+
+## Roadmap
+
+- [ ] Interactive Configuration UI (GUI for settings)
+- [ ] Save/Load config from JSON/YAML
+- [ ] Multi-monitor support
+- [ ] Custom skins/textures for bars
+
+## Disclaimer
+
+This software is an unofficial community tool. It is not affiliated with, endorsed by, or connected to 7th Beat Games (developers of A Dance of Fire and Ice) or any other game developer. Use responsibly.
+
+## License
+
+MIT License. See `LICENSE` for details.

core/__init__.py

@@ -0,0 +1,35 @@
+from PySide6.QtGui import QColor
+
+class Config:
+    # Visual Settings
+    SCROLL_SPEED = 800  # Pixels per second
+    BAR_WIDTH = 60      # Width of a single note bar
+    BAR_HEIGHT = 20     # Visual thickness of the bar (does not affect timing)
+    
+    # Lane Configuration
+    # Maps key strings (pynput format) to lane indices (0-based)
+    LANE_MAP = {
+        "'a'": 0,
+        "'s'": 1,
+        "'l'": 2,
+        "';'": 3
+    }
+    LANE_WIDTH = 70     # Horizontal spacing between lane starts
+    LANE_START_X = 50   # Starting X offset for the first lane
+
+    # Performance & Logic
+    MAX_BARS = 300      # Soft limit for object pool
+    INPUT_LATENCY_OFFSET = 0.0  # Seconds to add/subtract to align visual with audio
+    
+    # Fade Out Logic
+    # Position Y where fade starts (e.g., 80% down the screen)
+    FADE_START_Y = 800  
+    FADE_RANGE = 200    # Distance over which it fades to 0 opacity
+
+    # Debugging
+    DEBUG_MODE = True
+
+    # Colors (R, G, B, A)
+    COLOR_BAR = QColor(100, 200, 255, 200)
+    COLOR_BAR_BORDER = QColor(255, 255, 255, 230)
+    COLOR_DEBUG_TEXT = QColor(0, 255, 0, 255)

core/config.py

@@ -0,0 +1,86 @@
+import time
+from PySide6.QtCore import QObject, Signal, QThread
+from pynput import keyboard
+from .config import Config
+
+class InputWorker(QObject):
+    """
+    Worker that runs the pynput listener in a separate thread.
+    Emits (lane_index, timestamp) when a tracked key is pressed or released.
+    """
+    key_pressed = Signal(int, float)  # lane_index, timestamp
+    key_released = Signal(int, float) # lane_index, timestamp
+
+    def __init__(self):
+        super().__init__()
+        self.listener = None
+        self.running = False
+        self.active_keys = set() # Track pressed keys to filter autorepeats
+
+    def start_monitoring(self):
+        self.running = True
+        self.active_keys.clear()
+        self.listener = keyboard.Listener(on_press=self.on_press, on_release=self.on_release)
+        self.listener.start()
+        print("Input monitoring started.")
+
+    def stop_monitoring(self):
+        self.running = False
+        if self.listener:
+            self.listener.stop()
+            self.listener = None
+            print("Input monitoring stopped.")
+
+    def _get_key_str(self, key):
+        try:
+            return f"'{key.char}'"
+        except AttributeError:
+            return str(key)
+
+    def on_press(self, key):
+        if not self.running:
+            return
+        
+        k_str = self._get_key_str(key)
+        
+        # Filter autorepeat: If key is already in active_keys, ignore it
+        if k_str in self.active_keys:
+            return
+
+        if k_str in Config.LANE_MAP:
+            self.active_keys.add(k_str)
+            timestamp = time.perf_counter()
+            lane_idx = Config.LANE_MAP[k_str]
+            self.key_pressed.emit(lane_idx, timestamp)
+
+    def on_release(self, key):
+        if not self.running:
+            return
+
+        k_str = self._get_key_str(key)
+        
+        if k_str in self.active_keys:
+            self.active_keys.remove(k_str)
+
+        if k_str in Config.LANE_MAP:
+            timestamp = time.perf_counter()
+            lane_idx = Config.LANE_MAP[k_str]
+            self.key_released.emit(lane_idx, timestamp)
+
+class InputMonitor(QThread):
+    """
+    Thread wrapper for the worker.
+    """
+    key_pressed = Signal(int, float)
+    key_released = Signal(int, float)
+
+    def __init__(self):
+        super().__init__()
+        self.worker = InputWorker()
+        self.worker.key_pressed.connect(self.key_pressed.emit)
+        self.worker.key_released.connect(self.key_released.emit)
+
+    def run(self):
+        self.worker.start_monitoring()
+        self.exec()
+        self.worker.stop_monitoring()