> For the complete documentation index, see [llms.txt](https://xmmx-development.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://xmmx-development.gitbook.io/documentation/product-guides/20-vs-1-script.md).
# 20 vs 1 Script
Welcome to the official documentation for the `xmmx_twentyvsone` (20 vs 1 Balloon Pop Script & Props) resource used in custom FiveM servers. This GitBook will walk you through installing, configuring, and using the resource.
***
### 🔧 Installation
1. **Download & extract** this resource into your `resources/` directory.
2. **Ensure the resource is named** `xmmx_twentyvsone` (or update all references if renamed).
3. **Add to your `server.cfg`**:
```
ensure xmmx_twentyvsone
```
4. **Configure your `config.lua`** to match your items, models, distances, animations, and control keys.
5. Add the usable items to your inventory system (find them in the .INSTALL folder):
* `xm_balloon`
* `xm_needle`
* `xm_bp_backdrop`
6. Add item images to your inventory images folder (find them in the .INSTALL/images folder).
7. Add below listed dependencies to your server `resources/` directory:
***
### ✨ Features
* Fun balloon prop attachment & popping animation
* Balloon effects with screen shake and sound effects
* Support for QB-Core, QBX-Core, and ESX (configure others in bridge and editable)
* Optional prop placement system (backdrops)
* Optimized for performance and extensibility
***
### 📁 Installation Guide
#### 1. Download & Install
1. Place the resource in your `resources/[local]` folder:
```
resources/[local]/xmmx_twentyvsone
```
2. Ensure it is named exactly: `xmmx_twentyvsone`
#### 2. Add to server.cfg
```cfg
ensure xmmx_twentyvsone
```
***
### ⚖️ Dependencies
* A functional **inventory system** (supporting useable items)
* One of the following frameworks:
* `qb-core`
* `qbx_core`
* `es_extended`
***
### 🔧 Configuration
Edit `configs/config.lua` to fit your server's needs:
#### Commands
```lua
UseCommands = {
enabled = true,
balloon = "balloon",
backdrop = "backdrop",
}
```
> Enable command use without inventory items for testing.
#### Items
Make sure these item names match your inventory system:
```lua
NeedleItem = "xm_needle"
BalloonItem = "xm_balloon"
BackdropItem = "xm_bp_backdrop"
```
#### Models
```lua
BalloonModels = {
"xm3_prop_xm3_balloon_01a"
},
BackdropModel = "xmmx_bp_backdrop"
```
You can add more balloon models if available.
#### Effects
```lua
ShakeEffect = {
enabled = true,
effect = "SMALL_EXPLOSION_SHAKE",
amount = 0.075
}
```
***
### 🧠 Usage
#### ✨ Spawning a Balloon
If commands are enabled:\
`/balloon`
If using items:
* Use the `xm_balloon` item.
#### 📍 Spawning a Backdrop
`/backdrop` or use the `xm_bp_backdrop` item.
#### ✊ Popping Balloons
* Stand near a player with a balloon.
* Press `E` (default key: `38`)
* Must have `xm_needle` item in inventory
#### 📻 Screen Shake and Visual FX
* Nearby players will see a balloon pop animation
* Optional screen shake & audio
***
### 🧰 Integration
The resource includes automatic integration for QBCore, QBX, and ESX:
* Adds usable items for balloons & backdrops
* Handles balloon toggling and spawning
No changes are needed unless you're customizing item behavior. Do so in the server/editable.lua.
***
### 📫 Server Exports
#### `exports.xmmx_twentyvsone:ToggleBalloon(source)`
This export toggles the balloon prop for a player. It handles:
* Attaching a balloon model to the player's hand
* Playing a holding animation
* Syncing visibility to other clients
* Starting/stopping the idle loop animation
Usage:
```
exports.xmmx_twentyvsone:ToggleBalloon(source)
```
You can call this export manually or through item usage.
#### `exports.xmmx_twentyvsone:SpawnBackrop(source)`
This export spawns a backdrop object in front of the player and allows them to move/rotate it interactively using configured keys.
Usage:
```
exports.xmmx_twentyvsone:SpawnBackrop(source)
```
The player must own the configured `BackdropItem` to place the prop (unless command mode is enabled).
***
### ⚙️ Backdrop Controls
| Action | Key |
| -------------- | --------------- |
| Raise | Arrow Up |
| Lower | Arrow Down |
| Rotate Left | Scroll Down |
| Rotate Right | Scroll Up |
| Tilt Forward | Right Mouse Btn |
| Tilt Backward | Left Mouse Btn |
| Tilt Left | Left Arrow |
| Tilt Right | Right Arrow |
| Snap to Ground | Left Alt |
| Place Prop | Enter |
| Cancel | Backspace |
***
### 📆 Localization
You can easily change in-game Notifications and DrawText in `Config.Locales` table.
***
### 🚨 Troubleshooting
* **Nothing happens when using item**: Check that the item name matches your inventory database
* **Can't pop balloons**: Ensure you have the needle item in inventory
* **Animations not playing**: Make sure all required animation dictionaries exist
***
### ⚛️ Credits
* Script developed by **XMMX Development**
* Balloon model: Rockstar Games (GTA V)
* Custom assets and UI created for immersive events
***
### ✨ Coming Soon
* Multiple balloon model support
* Balloon colors or types
* Game-based events like 20vs1 game questionaire
***
For issues or suggestions, open a ticket via [discord](https://discord.com/invite/PjcNFcduzj).
Happy popping! 🎈