185 lines
7.0 KiB
Markdown
185 lines
7.0 KiB
Markdown
# Cursor Rush
|
|
|
|
A cross-platform application for customizing your cursor with gameified logic.
|
|
|
|
## Features
|
|
|
|
- Replace the system cursor with custom PNG images
|
|
- Minimize to system tray for background operation
|
|
- Windows support (macOS and Linux support in development)
|
|
- Optimized rendering with low CPU usage
|
|
- System tray integration with context menu
|
|
- Global hotkey support
|
|
- Steam integration for item drops
|
|
- Tauri-based frontend with React
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
frontend/
|
|
├── src/ # React frontend code
|
|
│ ├── App.jsx # Main React component
|
|
│ ├── components/ # UI components
|
|
│ └── cursors/ # Cursor image files
|
|
├── src-tauri/ # Rust backend code
|
|
│ ├── src/ # Rust source code
|
|
│ │ ├── lib.rs # Main library code
|
|
│ │ ├── main.rs # Application entry point
|
|
│ │ ├── integrations/ # External integrations
|
|
│ │ │ ├── mod.rs # Integrations module exports
|
|
│ │ │ └── steam.rs # Steam integration
|
|
│ │ └── platform/ # Platform-specific code
|
|
│ │ ├── mod.rs # Platform module exports
|
|
│ │ ├── types.rs # Common type definitions
|
|
│ │ ├── windows/ # Windows-specific code
|
|
│ │ ├── macos/ # macOS-specific code
|
|
│ │ └── linux/ # Linux-specific code
|
|
│ └── Cargo.toml # Rust dependencies
|
|
└── package.json # npm dependencies
|
|
```
|
|
|
|
## Building
|
|
|
|
### Prerequisites
|
|
|
|
- Rust 1.56.0 or later (tested with 1.86.0)
|
|
- Cargo
|
|
- Node.js 16.0.0 or later (tested with 20.11.0)
|
|
- npm 7.0.0 or later (tested with 10.2.4)
|
|
- Platform-specific dependencies:
|
|
- Windows: Visual Studio Build Tools (fully supported)
|
|
- macOS: Development in progress
|
|
- Linux: Development in progress
|
|
|
|
### Dependencies
|
|
|
|
The application uses the following major dependencies:
|
|
- Tauri 1.8.3 - Cross-platform framework
|
|
- React 19.1.0 - Frontend framework
|
|
- image 0.24 - Image processing
|
|
- winapi 0.3.9 - Windows API bindings
|
|
- once_cell 1.19.0 - Lazy initialization
|
|
- steamworks 0.11.0 - Steam integration
|
|
- parking_lot 0.12.3 - High-performance synchronization
|
|
|
|
### Build Commands
|
|
|
|
```bash
|
|
# Navigate to the frontend directory
|
|
cd frontend
|
|
|
|
# Install npm dependencies
|
|
npm install
|
|
|
|
# Run in development mode (starts both frontend and backend)
|
|
npm run tauri dev
|
|
|
|
# Build for production
|
|
npm run tauri build
|
|
|
|
# Alternative: Run frontend and backend separately for debugging
|
|
# Terminal 1: npm run dev (starts Vite dev server)
|
|
# Terminal 2: npm run tauri dev --no-dev-server (starts Tauri without dev server)
|
|
```
|
|
|
|
## Usage
|
|
|
|
1. Make sure you have Node.js and npm installed
|
|
2. Navigate to the frontend directory: `cd frontend`
|
|
3. Install dependencies if you haven't already: `npm install`
|
|
4. Run the application in development mode: `npm run tauri dev`
|
|
5. The application will start with a React frontend and Rust backend
|
|
6. Use the UI to browse and select cursors
|
|
7. The application will replace your system cursor with the selected image
|
|
8. To exit, use the "Quit" button in the application or from the system tray
|
|
|
|
### Custom Cursors
|
|
|
|
The application comes with sample cursors:
|
|
- `default.png` - A simple default cursor
|
|
- `icon.png` - An icon cursor
|
|
- `red.png` - A red-colored cursor
|
|
|
|
To add your own cursors:
|
|
1. Create PNG or CUR images with transparent backgrounds
|
|
2. Place them in the `frontend/src/cursors` directory
|
|
3. Restart the application to load the new cursors
|
|
4. The cursor name in the UI will be derived from the filename
|
|
|
|
**Note**: The application automatically scans multiple directories for cursor files:
|
|
- `frontend/src/cursors/` (recommended location)
|
|
- `frontend/src-tauri/src/cursors/`
|
|
- `frontend/src-tauri/cursors/`
|
|
|
|
## Hotkeys
|
|
|
|
- Ctrl+Shift+F12: Exit the application (restores original system cursor)
|
|
- If this hotkey fails, the application will try to use Ctrl+Alt+F12 or F12 as fallbacks
|
|
|
|
## System Tray
|
|
|
|
- Left-click: Show the application window
|
|
- Right-click: Open the context menu with the following options:
|
|
- Next cursor: Switch to the next cursor in the list
|
|
- Show window: Show the application window
|
|
- Quit: Exit the application and restore the original cursor
|
|
|
|
## Performance
|
|
|
|
- The application uses optimized rendering techniques to minimize CPU usage
|
|
- On Windows, it uses the Windows API to efficiently replace system cursors
|
|
- The application uses event-driven cursor updates instead of polling when possible
|
|
- Cursor images are cached to improve performance when switching between cursors
|
|
|
|
## Known Issues & Status
|
|
|
|
### Recently Fixed Issues
|
|
The following issues have been addressed in recent updates:
|
|
- Task Manager compatibility: The application now properly handles elevated applications
|
|
- System tray menu stability: Fixed issues with the tray menu disappearing when mousing over it
|
|
|
|
### Current Known Issues
|
|
- Some system tray menu interactions may still be inconsistent on certain Windows versions
|
|
- Z-ordering issues where custom cursor may hide behind system tray menus due to Windows UI prioritization
|
|
- Performance may be affected when Task Manager or other elevated applications are open due to Windows security restrictions
|
|
|
|
## Steam Integration
|
|
|
|
The application includes integration with the Steam API (AppID: 1430270):
|
|
- Shows as an active game in Steam for time tracking purposes
|
|
- Steam integration initializes automatically when the application starts
|
|
- Item drop functionality is implemented but not yet active
|
|
- Steam must be running for the integration to work properly
|
|
- The application will appear in your Steam library as "running" while active
|
|
|
|
## Troubleshooting
|
|
|
|
### Build Issues
|
|
- **Missing Visual C++ Redistributable**: Install Visual Studio Build Tools or Visual C++ Redistributable packages
|
|
- **Node.js library issues**: Reinstall Node.js (version 16.0.0 or later) and ensure all dependencies are properly installed
|
|
- **Rust compilation errors**: Ensure Rust 1.56.0 or later is installed and up to date
|
|
|
|
### Runtime Issues
|
|
- **Application won't start**: Check that all dependencies are installed and Steam is running (if using Steam integration)
|
|
- **Cursor not changing**: Verify cursor files exist in the correct directory and have proper file permissions
|
|
- **System tray issues**: Try restarting the application or check Windows notification area settings
|
|
|
|
### Development Issues
|
|
- **Tauri dev server not starting**: Ensure port 5173 is available or specify a different port
|
|
- **Hot reload not working**: Check that the Vite dev server is running properly in the background
|
|
|
|
## Contributing
|
|
|
|
Contributions to Cursor Rush are welcome! Here are some ways you can contribute:
|
|
|
|
- Report bugs and issues
|
|
- Suggest new features or improvements
|
|
- Submit pull requests with bug fixes or new features
|
|
- Help with documentation
|
|
- Contribute to macOS and Linux platform support
|
|
- Improve the Tauri integration
|
|
|
|
## License
|
|
|
|
This project is currently in development and does not yet have a specified license. A license will be added in a future update.
|