Advanced Modular HaxBall Desktop Client
Unlock FPS • Custom Avatars • Discord RPC • Background Customization • And More
Vexa is a feature-rich desktop client for HaxBall, built on Electron. It wraps the official HaxBall web game and injects powerful quality-of-life enhancements, performance optimizations, and a modern settings UI — all without modifying the game's core code.
| Feature | Description |
|---|---|
| 🎯 Unlocked FPS | Bypass the browser's 60 FPS cap — sync to your monitor's native refresh rate (144Hz, 240Hz, etc.) |
| 📊 FPS Counter & Net Graph | Real-time FPS display and network performance graph overlay |
| 🎨 Custom Avatars | 10-slot avatar carousel with quick-switch — use any emoji, text, or symbol |
| 🖼️ Custom Backgrounds | Upload your own wallpapers with a 5-item history grid — persisted across sessions |
| 🎮 Discord Rich Presence | Show your HaxBall activity on Discord with room info and player count |
| ⚡ Ping Booster | Optional TCP_NODELAY optimization for reduced input latency |
| ⌨️ Chat Shortcuts | /a <text> to change avatar, /e <value> to set extrapolation, and more |
| 👤 Player Profiles | Multi-profile system — save and switch between different nicknames, avatars, and settings |
| 🔧 HaxAllTool Integration | Built-in browser extension tools: room search, auto-join, favorites, emoji chat, admin tools |
| 🚀 Auto-Updater | Launcher automatically checks for and installs updates from GitHub Releases |
vexa/
├── launcher/ # Vexa Launcher (updater & game bootstrapper)
│ ├── main.js # Launcher Electron main process
│ ├── installer.js # Download & update manager
│ ├── preload.js # Launcher preload bridge
│ └── ui/ # Launcher frontend (HTML/CSS/JS)
├── electron/ # Game Client (core Electron wrapper)
│ ├── main.js # Client main process, IPC handlers
│ ├── window.js # BrowserWindow factory & script injection
│ ├── preload.js # Client preload API (settings, backgrounds)
│ ├── settings.js # Persistent settings manager (JSON file)
│ ├── splash.html # Splash screen
│ └── customSign.js # Custom code signing utility
├── inject/ # Injected scripts (run inside HaxBall page)
│ ├── client.js # FPS engine, limiter, counter, net graph
│ ├── header.js # Settings UI, top bar, tabs (General/Shortcuts/Profiles/Backgrounds)
│ ├── avatar.js # 10-slot avatar carousel system
│ ├── profiles.js # Multi-profile management
│ ├── ui.js # UI utilities
│ └── hx_polyfill.js # HaxBall API polyfills
├── hxalltool/ # HaxAllTool browser extension (embedded)
├── build/ # Build resources (icons, installer images)
├── .github/workflows/ # GitHub Actions CI/CD
└── package.json # Project manifest & build configuration
# Clone the repository
git clone https://github.com/vexa-client/vexa.git
cd vexa
# Install dependencies
npm install
# Run in development mode
npm start# Build Launcher installer (.exe)
npm run build
# Build Client package (portable)
npm run build:client
# Build everything (Launcher + Client + Package)
npm run build:fullBuild artifacts are output to the dist/ directory.
The entry point of Vexa. It checks GitHub Releases for the latest client version, downloads and extracts it, then launches the game client as a child process. Features a sleek dark UI with progress tracking.
The core Electron wrapper that loads html5.haxball.com and injects Vexa's enhancement scripts. Handles IPC for settings persistence, custom background file management, and Discord RPC.
JavaScript files injected into the HaxBall page at runtime:
- client.js — FPS unlocking via
requestAnimationFrameoverride, real-time FPS counter, network graph - header.js — Complete settings UI with 4 tabs (General, Shortcuts, Profiles, Backgrounds)
- avatar.js — 10-slot avatar system with drag-and-click selection
- profiles.js — Save/load player profiles (nick, avatar, country, settings)
An embedded browser extension providing room search, auto-join, favorites, admin tools, emoji support, and chat translation.
Settings are persisted in %APPDATA%/vexa-client/settings.json and include:
| Setting | Default | Description |
|---|---|---|
fpsEnabled |
true |
Enable/disable FPS limiter (unlocked when disabled) |
fpsShow |
true |
Show FPS counter overlay |
rpcEnabled |
true |
Enable Discord Rich Presence |
pingBoosterEnabled |
false |
Enable TCP_NODELAY for lower latency |
netGraphEnabled |
true |
Show network performance graph |
Custom backgrounds are stored in %APPDATA%/vexa-client/backgrounds/.
The project uses GitHub Actions for automated builds and releases:
- Trigger: Push a version tag (e.g.,
v1.1.14) - Pipeline: Install → Build Launcher → Build Client → Package → Create GitHub Release
- Output: NSIS installer (
.exe) + portable client package (app.zip)
# Create a new release
git tag v1.1.14
git push origin v1.1.14- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the GNU General Public License v3.0 — see the LICENSE file for details.
- 🌐 Website: vexa.gg
- 💬 Discord: Join Server
- 📦 Releases: GitHub Releases
- 🐛 Issues: Report a Bug
Made with ❤️ by Vexa