93 lines
3.0 KiB
Markdown
93 lines
3.0 KiB
Markdown
|
# 🗺️ 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 |
|