prp-trashhunt
A full-featured scavenging and salvage system for FiveM. Players search dumpsters, trash cans, bins, bags, recycle bins, and industrial skips to collect materials, craft useful items, and build reputation. Every search is a server-validated mini-game with loot gating, hazards, cooldowns, and progression.
Features
- 6 container types with unique loot tables, durations, and hazard profiles
- Canvas mini-game with click/controller/keybind input, combo system, and score-gated loot
- Server-authoritative rewards, cooldowns, and anti-cheat validation
- 16-level reputation system with hourly caps and progressive crafting unlocks
- 11 crafting recipes gated by rep level and license tokens
- 6 recycling recipes for on-site processing at recycle bins and industrial skips
- Item disposal system that converts unwanted items into scrap metal and rep
- Dynamic hot zones with time-based activation and loot/hazard multipliers
- Job bonuses for police, EMS, fire, and tow operators
- Hazard system including needle pokes, roach swarms, toxic fumes, alarms, and persistent infection
- Time bonus pickups that extend round duration during the mini-game
- Full accessibility support: reduced motion, screen shake toggle, colorblind mode with distinct shapes per tier
- Multi-framework support: Qbox, QBCore, ESX with auto-detection
- Multi-language support: English, Spanish, French, German, Portuguese (BR), Turkish
- Discord webhook logging for search events, rewards, and validation failures
- Keybind support (default F key) as an alternative to ox_target interaction
- Controller support with aim assist and gamepad input during the mini-game
- Demo mode for testing without server-side effects
Requirements
| Dependency | Required | Notes |
|---|---|---|
ox_lib |
Yes | Core dependency |
ox_target or qb-target |
Yes | Container interaction |
ox_inventory |
Recommended | Also supports QBCore and ESX inventory |
qbx_core, qb-core, or es_extended |
Yes (one) | Framework adapter |
oxmysql |
Optional | Only needed for database rep persistence |
Container Types
Each container has different search duration, loot quality, cooldowns, and risk.
| Container | Duration | Cooldown | Player CD | Rep | Noise | Best Loot |
|---|---|---|---|---|---|---|
| Trash Bag | 3.2s | 70s | 4s | +4 | 8% | Low (mostly cloth/plastic) |
| Trash Can | 5.6s | 120s | 6s | +7 | 13% | Medium |
| Trash Bin | 6.7s | 150s | 7s | +9 | 16% | Medium |
| Recycle Bin | 6.2s | 145s | 6s | +8 | 12% | Medium-High (sort mode) |
| Dumpster | 8.5s | 210s | 8s | +12 | 20% | High |
| Industrial Skip | 9.3s | 260s | 10s | +14 | 24% | Highest |
Cooldowns are per-container (the specific object) and per-player (global). A player cannot spam the same container or hop between containers without waiting.
Noise attracts attention. Higher noise chance containers are riskier but more rewarding. When zombie integration is enabled, noise can attract zombies.
Mini-Game
When a player searches a container, a canvas-based mini-game launches. Items float across the screen and the player clicks to grab them before time runs out.
How It Works
- Items spawn on a budget system. Each round has a fixed spawn budget split between junk, bonus, ultra, hazard, and time bonus items.
- Click to grab good items for points. The score is normalized to 0-100%.
- Avoid hazards (red items with skull/danger icons). Clicking a hazard loses points and breaks your combo.
- Build combos by grabbing items in sequence. Combo multiplier caps at x5 and changes color as it grows.
- Near-miss forgiveness prevents frustration. Clicks within 30px of an item still count (with slightly reduced points).
- Time bonus pickups (cyan hourglass) add +1.5 seconds to the timer. Up to 2 can spawn per round in 5+ second rounds.
Scoring & Loot Gating
Your mini-game score directly affects loot quality:
| Score | Loot Access |
|---|---|
| 0-39% | Junk pool only |
| 40-74% | Junk + Bonus pool |
| 75%+ | Junk + Bonus + Ultra pool |
| 95%+ (no hazard hits) | Perfect round bonus (+1 rep, confetti) |
Recycle Bin Sort Mode
Recycle bins feature a special sort mode. Items must be dragged to the correct lane (Materials or Electronics). Correct sorting grants a combo shield that protects your streak. Wrong sorting spawns a hazard as penalty.
Reputation & Progression
Players earn rep with every search and use it to unlock crafting recipes.
Level Thresholds
| Level | Rep Required | Level | Rep Required |
|---|---|---|---|
| 0 | 0 | 8 | 1,830 |
| 1 | 60 | 9 | 2,400 |
| 2 | 150 | 10 | 3,080 |
| 3 | 280 | 11 | 3,880 |
| 4 | 450 | 12 | 4,810 |
| 5 | 680 | 13 | 5,880 |
| 6 | 980 | 14 | 7,100 |
| 7 | 1,360 | 15 | Beyond |
Hourly Cap: Rep gain is capped at 400 per hour to prevent grinding exploits.
Crafting
Crafting recipes are unlocked by reaching specific rep levels and holding license tokens.
Recipe Table
| Recipe | Output | Ingredients | Time | Min Level |
|---|---|---|---|---|
| Duct Tape | 1x duct_tape | 2x plastic, 1x rubber | 3s | 1 |
| Zip Ties | 2x ziptie | 2x plastic, 1x rubber | 4s | 2 |
| Salvage Antidote | 1x salvage_antidote | 2x aluminum, 1x cloth, 1x battery | 4s | 1 |
| Tool Kit | 1x screwdriverset | 4x metalscrap, 2x duct_tape, 2x rubber | 5s | 2 |
| Med Patch | 1x med_patch | 3x cloth, 2x aluminum, 1x duct_tape | 5s | 3 |
| Repair Kit | 1x repairkit | 6x scrapmetal, 2x duct_tape, 1x wiring_bundle | 6s | 2 |
| Wiring Bundle | 1x wiring_bundle | 4x copper, 1x duct_tape | 5s | 3 |
| Battery Pack | 1x battery_pack | 3x battery, 3x copper, 2x plastic | 6s | 3 |
| Filter Mask | 1x filter_mask | 4x cloth, 2x rubber, 1x battery_pack | 7s | 3 |
| Radio Parts | 1x radio_parts | 2x electronickit, 1x circuit_board, 1x wiring_bundle | 7s | 4 |
| Circuit Board | 1x circuit_board | 3x electronickit, 2x aluminum, 2x wiring_bundle | 8s | 5 |
Recycling & Disposal
Recycling
Available at recycle bins and industrial skips. Players select a recipe from a dialog menu and process materials on-site.
Disposal
Players can throw away unwanted items at recycling containers. Disposed items are removed from inventory and converted into scrap metal based on item weight, plus a small rep reward.
Hot Zones
Hot zones are map areas where loot quality, hazard risk, and rep gain are amplified.
- Cypress Industrial Zone: Active 6:00 PM - 5:00 AM. +35% bonus loot, +20% ultra loot, +30% noise.
- Textile Dump Route: Always active. +20% bonus loot, +10% ultra loot.
Hazards & Infection
Each container type has independent hazard chances. Hazards trigger after the search completes (server-side roll).
| Hazard | Effect | Mitigation |
|---|---|---|
| Needle Poke | 4-8 damage, 5s movement slow | Higher containers have higher chance |
| Roach Swarm | Screen distortion, 2.5s slow | Visual effect only, minor slowdown |
| Toxic Fumes | 6-10 damage, 7s severe slow | Blocked entirely by holding a filter mask |
| Alarm | Forced noise trigger | No mitigation |
| Infected Cut | 5-8 initial damage + recurring DOT | Use salvage_antidote item or /useantidote |
Job Bonuses
Certain jobs receive passive bonuses when searching containers.
| Job | Search Speed | Hazard Resist | Noise Reduction | Cooldown |
|---|---|---|---|---|
| Police | 6% faster | 12% less damage | 5% quieter | 5% shorter |
| EMS/Ambulance | 3% faster | 14% less damage | - | 5% shorter |
| Fire | 5% faster | 16% less damage | 4% quieter | 6% shorter |
| Tow | 7% faster | 10% less damage | 2% quieter | 8% shorter |
Commands
Player Commands
/useantidote- Cure infection (requires antidote item in inventory)
Console Commands
trashhunt_export_recipes- Export all crafting recipes to JSONtrashhunt_rep_sql- Print SQL for the rep tabletrashhunt_item_audit- Audit all configured items against ox_inventory
Demo Command
/trashhunt_demo [type] [duration] [difficulty] - Test the mini-game without server effects.
Example: /trashhunt_demo dumpster 9 master