🗺️ rv-maphold — Physical Map System

A standalone FiveM resource for QBCore that adds a physical map item to the game. Players must own a map item to see blips on the pause menu map. Using the item from inventory opens the map with a realistic map-holding animation.

✨ Features

Blip Visibility Control — Without the map item, all map blips are hidden (empty map)
Map Animation — When opening the pause menu with the map item, the player holds a physical map in their hands (WORLD_HUMAN_TOURIST_MAP)
Inventory USE Action — Players can USE the map item from inventory to open the pause menu map directly
Starter Item — Map is given automatically to new characters via QBShared.StarterItems
Standalone — No dependencies other than qb-core and qs-inventory

📦 Installation

1. Copy Resource

Place the rv-maphold folder in your server's resources directory:

resources/[framework]/[addons]/rv-maphold/

2. Add Item to `qb-core/shared/items.lua`

['map'] = {['name'] = 'map', ['label'] = 'Map', ['weight'] = 100, ['type'] = 'item', ['image'] = 'map.png', ['unique'] = false, ['useable'] = true, ['shouldClose'] = true, ['combinable'] = nil, ['description'] = 'A physical map of Los Santos and Blaine County'},

3. Add as Starter Item (optional)

In qb-core/shared/main.lua, add map to QBShared.StarterItems:

QBShared.StarterItems = {
    -- ... existing items ...
    ['map'] = { amount = 1, item = 'map' },
}

4. Add Item Image

Place a map.png icon (128x128 recommended) in your inventory's image folder:

qs-inventory/html/images/map.png

5. Ensure Resource

Add to your resources.cfg (after qb-core and qs-inventory):

ensure rv-maphold

6. Restart Server

ensure rv-maphold

⚙️ How It Works

Scenario	Behavior
Player has `map` item	Blips visible on pause menu, animation plays when opening map
Player doesn't have `map` item	Blips hidden, pause menu still works but map is empty
Player USEs map from inventory	Pause menu opens on MAP tab + map animation

🔧 Configuration

No configuration needed. The resource works out of the box.

To disable the blip hiding feature, comment out the SwitchBlips loop in client.lua.

📁 File Structure

rv-maphold/
├── fxmanifest.lua    # Resource manifest
├── client.lua        # Blip control, animation, USE handler
├── server.lua        # RegisterUsableItem for 'map'
└── README.md         # This file

🔗 Dependencies

Resource	Required	Notes
`qb-core`	✅ Yes	Framework — provides `QBCore`, `CreateUseableItem`
`qs-inventory`	✅ Yes	Inventory system — handles item USE action

📝 Credits

Red Valley Community — Original development
Inspired by sm_map (ScriptsM) for the animation concept

📋 Version History

Version	Date	Changes
1.0.0	2026-04-01	Initial release — blip hiding + map animation + inventory USE

3.0 KiB Raw Blame History