# 🗺️ 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`
```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`:
```lua
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`):
```cfg
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 |