🎈20 vs 1 Script

Installation Guide!

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:

Dependency Name:	Dependency Link:
ox_lib	Download latest release, HERE.
xmmx_bridge	Included or download for free, HERE.

---

✨ 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

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

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:

NeedleItem = "xm_needle"
BalloonItem = "xm_balloon"
BackdropItem = "xm_bp_backdrop"

Models

BalloonModels = {
    "xm3_prop_xm3_balloon_01a"
},
BackdropModel = "xmmx_bp_backdrop"

You can add more balloon models if available.

Effects

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.

Happy popping! 🎈