# 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! 🎈
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://xmmx-development.gitbook.io/documentation/product-guides/20-vs-1-script.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.