Create README.md

resources/[framework]/[addons]/rv-maphold/README.md

@@ -0,0 +1,92 @@
+# 🗺️ 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 |