Premium Pipe Dream-style hacking minigame
Hacking minigame for FiveM. Free, MIT licensed, framework-agnostic. Premium API, tablet animation, AI integration ready.
# Circuit Hack
> Premium Pipe Dream-style hacking minigame for FiveM. Free forever.
[VECTORZEN[U] · /CIRCUIT_HACK]
## ⚡ Why Circuit Hack?
Most FiveM hacking minigames are timing-based skill checks completed in seconds. Circuit Hack is different — a **spatial puzzle** where players actively rotate circuit pieces to connect IN → OUT, with the visual paradigm of the legendary Pipe Dream (1989).
**Built for server owners who want their hacks to *feel* like hacks.**
---
## 🎮 Features
### Gameplay
- **Pipe Dream visual paradigm** — instantly recognizable, zero learning curve
- **3 difficulty tiers** — Easy 4×4 (45s), Medium 6×6 (30s), Hard 8×8 (25s)
- **Auto-balanced grids** — generator validates click counts within target ranges
- **Energy flow effects** — completed paths pulse with electric brightness
- **Tablet animation** — player ped plays tablet animation with prop attached
### Developer Experience
- **Premium API v2** — 5 callbacks (`onStart`, `onSuccess`, `onFail`, `onCancel`, `onCooldown`)
- **Server-side hooks** — `vzu-circuit-hack:onSuccess` etc. for cross-resource integration
- **Cooldown system** — Per-context cooldowns (atm, vehicle, door, computer, safe)
- **Player stats** — Attempts, success rate, leaderboards via `GetTopPlayers`
- **Optional persistence** — Stats and cooldowns survive restarts via oxmysql
- **Anti-cheat** — Server-side validation, session nonce, rate limiting
### Production Ready
- **6 SFX included** — Tile rotate, path connect, lock-in loop, success/fail
- **Locale system** — EN default, PT-BR included, easily extensible
- **5 ready-to-use examples** — ATM, vehicle lockpick, door breach, computer hack, safe crack
- **Test zone resource** — `/vzutest` commands for instant scenario testing
- **AI Integration Ready** — `LLM_CONTEXT.md` for Claude Code, Cursor, Copilot, Codex
---
## 🚀 Quick Integration
```lua
exports['vzu_circuit_hack']:Start('medium', function(success)
if success then
TriggerServerEvent('myresource:reward')
end
end)
```
That's it. Three lines.
For richer integrations, the v2 API supports per-call config, cooldowns, and 5 callbacks. See [API.md](https://github.com/vizuugit/vzu_circuit_hack/blob/main/docs/API.md).
---
## 🤖 AI Integration
Using Claude Code, Cursor, GitHub Copilot, or Codex?
Paste `LLM_CONTEXT.md` into your AI conversation. The AI generates production-ready integration code without inventing exports — first FiveM script optimized for AI workflows.
**Example prompt:**
> "Add an ATM hack to my Qbox server with police alarm 30s after start, $1500 reward on success."
The AI produces working Lua code in seconds.
---
## 🎯 Compatibility
| Framework | Status |
|-----------|--------|
| Qbox | ✅ Native |
| QBCore | ✅ Bridge |
| ESX | ✅ Bridge |
| Standalone | ✅ Works without framework |
| Inventory | Status |
|-----------|--------|
| ox_inventory | ✅ Recommended |
| qb-inventory | ✅ Compatible |
| esx_inventoryhud | ✅ Compatible |
---
## 📦 Dependencies
- **Required:** [ox_lib](https://github.com/overextended/ox_lib)
- **Optional:** [oxmysql](https://github.com/overextended/oxmysql) (for persistence)
---
## ⚙️ Performance
- **Idle:** 0.00ms server, 0.00ms client
- **Active hack:** ~0.05ms client (NUI rendering only)
- **Network:** 1 callback round-trip per hack
Tested up to 64 concurrent players on FXServer build 7290+.
---
## 📚 Documentation
Comprehensive docs included:
- README — Overview, features, quick start
- INSTALL — Step-by-step installation
- API — Complete reference with TypeScript-style annotations
- CONFIGURATION — All 30+ options explained
- EVENTS — Server-side hooks for integration
- INTEGRATION_EXAMPLES — 10 patterns for common scenarios
- TROUBLESHOOTING — Common issues + fixes
- MIGRATION — Coming from mhacking, qb-skillbar, ox_lib skillCheck
- FAQ — 25+ questions answered
- CONTRIBUTING — How to contribute
- LLM_CONTEXT — AI-optimized reference
**Total:** ~3500 lines of documentation in English.
---
## 🛠️ Bundled Examples
5 production-ready integrations in `examples/`:
| Example | Scenario |
|---------|----------|
| 01_atm_robbery | ATM hack with cooldown, marked bills, optional Discord webhook |
| 02_vehicle_lockpick | Lockpick with difficulty modulated by vehicle class |
| 03_door_breach | Electronic doors with keycard fallback |
| 04_computer_hack | 3 tiers (residential/corporate/military) with loot tables |
| 05_safe_crack | Safes with loot tier system |
Each is **copy-paste-ready** and **framework-agnostic**.
---
## 🎬 Demo
[https://youtu.be/WxVS-Cp6Paw?si=hjRrfycWCWAE6MM5]
---
## 📜 License
MIT License — free to use, modify, distribute. Even in commercial server projects.
---
## 🎨 About VZU Studio
VZU (Vector Zen Underground) is an independent FiveM script studio focused on premium quality, polished UX, and developer-first APIs.
**Coming Soon:**
- 🎯 **Circuit Hack PRO** — 6 themed variants, camera system, advanced callbacks (~$60)
- 📱 **VZU Underground Apps** — Drug dealer, stock trading, marketplace LB Phone apps
- 🔓 **VZU Heist Pack** — Yacht, Bank, Casino vault heists
Follow VZU on [Twitter](https://twitter.com/vizuu3d) · [GitHub](https://github.com/vizuugit)
---
## 🐛 Support
- **GitHub Issues:** Bug reports, feature requests
- **Email:** vizuu3d@gmail.com (commercial inquiries)
---
**This is our first public release. Circuit Hack will always be free.**
Built with ❤ in Brazil.