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 "Rain" mode found in various rhythm game mods. It provides visual feedback on rhythm stability, micro-jitter, and input timing without injecting code into game process.

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.

• External overlay with transparent, always-on-top, click-through window
• Graphic interface for live configuration
• Configurable X/Y overlay positioning
• Supports both Down (Classic) and Up (Reverse) fall directions
• High-resolution monotonic clocks for smooth animation
• Configurable key-to-lane mapping (e.g., WASD, Space, Enter)
• Visual keyboard representation showing key presses and counts
• Adjustable opacity for inactive keys
• Customizable RGBA colors and overlay speed
• Long press support with variable-length bars
• Performance optimized with object pooling and efficient rendering

• Python 3.10+
• PySide6 (Qt) for high-performance rendering and window management
• pynput for global low-level keyboard hook
• pywin32 for Windows API integration

RainingKeysPython/
├── core/
│   ├── configuration.py    # Dataclasses for application configuration
│   ├── gui.py              # Configuration Window GUI
│   ├── input_mon.py        # Global input listener (thread-safe)
│   ├── logging_config.py   # Logging configuration
│   ├── overlay.py          # Main rendering loop and window logic
│   ├── settings_manager.py # Handles config loading/saving (atomic writes, migration)
│   └── ui/
│       ├── components.py     # Reusable UI components
│       └── theme.py         # Theme definitions
├── .github/
│   ├── workflows/
│   │   ├── ci.yml           # Code quality validation (Windows)
│   │   └── release.yml     # Automated releases with git-cliff
│   ├── scripts/
│   │   ├── syntax_check.py      # Python syntax validation
│   │   ├── type_check.py        # Type hints validation
│   │   ├── config_validation.py  # Configuration validation
│   │   └── monitor_ci.py       # CI monitoring script
│   └── README.md             # Workflow documentation
├── cliff.toml               # Git-cliff configuration for changelog generation
├── run_local_ci.py          # Local CI runner script
├── build.py                 # Build script for creating standalone executable
├── main.py                  # Application entry point
└── requirements.txt           # Dependencies

1. Ensure you have Python 3.10 or newer installed
2. Clone repository or download source
3. Install dependencies:

pip install -r requirements.txt

For a portable executable without Python installation:

python build.py

This creates RainingKeysPython.exe in the dist/ folder.

1. Run the application:

python main.py

2. The application launches two windows:

• Transparent Overlay: The visualizer (click-through)
• Config Window: The controls (Alt+Tab to find if hidden)

3. Configure lanes:

• Click "Record Lane Keys" in the config window
• Press keys to bind (e.g., Z, X, ., /)
• Click "Stop Recording" to save

4. Customize settings:

• Adjust Scroll Speed and Bar Color
• Enable KeyViewer to see the static key panel
• Drag Inactive Opacity to change faintness of unpressed keys
• Change KeyViewer Position (Above/Below) to flip fall direction

Settings are stored in config.ini (automatically created on first run). You can edit this file manually or use the GUI Settings Window.

The configuration file includes a CONFIG_VERSION field for automatic migration. When updating to a new version with breaking config changes, the application will automatically migrate your settings.

This project is open to contributions. For detailed development guides, see the following documentation:

• AGENTS.md - Core components and architecture
• GITHUB_WORKFLOWS.md - CI/CD workflow documentation
• GIT_CLIFF_MIGRATION.md - Git-cliff migration guide
• .github/README.md - Workflow directory reference

1. Run local CI (fast quality check):

python run_local_ci.py

2. Install dependencies:

pip install -r requirements.txt

3. Make changes and test locally:

python run_local_ci.py

4. Commit with conventional format:

git commit -m "feat: Add new feature"

5. Push to GitHub:

git push

See LOCAL_CI.md for complete local CI runner documentation.

This project uses GitHub Actions for automated quality validation and release management.

• Runs on every push and pull request
• Windows-based CI for consistency with production
• Syntax validation, linting, type checking, import testing

• Triggered by tag push (format: v*)
• Generates changelog using git-cliff
• Creates GitHub releases with build artifacts:
  • RainingKeysPython.zip - Release build
  • RainingKeysPython-debug.zip - Debug build

Use the following format for commit messages:

<type>[optional scope]: <subject>

[optional body]

[optional footer(s)]

Types: feat, fix, perf, refactor, chore, test, docs, style

Run GitHub Actions CI checks locally for faster development iteration.

# Run all checks
python run_local_ci.py

# Run individual checks
python run_local_ci.py --syntax    # Syntax check
python run_local_ci.py --lint      # Linting
python run_local_ci.py --import    # Import check
python run_local_ci.py --type      # Type check
python run_local_ci.py --config    # Config check
python run_local_ci.py --build     # Build test

• 10-100x faster than GitHub Actions
• Interactive debugging
• Unlimited runs
• Free (uses own computer)
• Same environment as development (Windows)

Contributions are welcome! We'd love to make this tool better together.

Open an Issue and tell us about it!

Fork repository and submit a Pull Request.

1. Run local CI: python run_local_ci.py
2. Use conventional commits (format above)
3. Write tests for new features
4. Update documentation where needed

This project is inspired by RainingKeys mod for A Dance of Fire and Ice, originally created by paring-chan.

Also credits to AdofaiTweaks by PizzaLovers007.

MIT License. See LICENSE for details.

• GitHub Repository
• Releases
• Issues
• AGENTS.md - Developer Guide
• GITHUB_WORKFLOWS.md - CI/CD Documentation
• GIT_CLIFF_MIGRATION.md - Migration Guide
• LOCAL_CI.md - Local CI Runner

Made with love by the RainingKeysPython community