🎈Hot Air Balloons! Script

Installation Guide (Coming Soon)

Welcome to the official installation guide for the xmmx_hotairballoons resource. This script brings immersive hot air balloon experiences to your FiveM server with smooth animations, camera controls, and interactive seats.

---

📦 Dependencies

Ensure you have the following resources installed before using this script:

1. ox_lib – UI and utility functions

2. xmmx_bridge – Bridge between UI elements and your logic

---

🔧 Config

File: config.lua

Here's a breakdown of important config options you can customize:

⚙️ General

Version  = true   -- Enable script version checking?
Debug    = false  -- Enable debug print messages?
Model    = "balloon" -- The in-game model to use for the hot air balloon

🪑 Seat Settings

Seats = {
    AllowExit = false,     -- Prevent players from exiting in the air
    ExitKey   = 73,        -- Default: X key

    Offsets = {
        [1] = { coord = vec3(0.10, 0.45, 0.25),  rot = 0.0   }, -- Front Centered
        [2] = { coord = vec3(-0.45, 0.10, 0.25), rot = 90.0  }, -- Left Centered
        [3] = { coord = vec3(0.45, -0.10, 0.25), rot = 270.0 }, -- Right Centered
        [4] = { coord = vec3(0.10, -0.45, 0.25), rot = 180.0 }, -- Rear Centered
    },

    Animation = {
        enable = true, -- enable the animation while in the balloon?
        Dict   = "anim@amb@nightclub@lazlow@ig1_vip@",
        Clip   = "clubvip_base_laz",
        Flag   = 49
    },
}

🗺 Blip Settings

Blips = {
    enableBlips = true,
    blipLabel   = "Hot Air Ballon",
    blipSprite  = 94,
    blipDisplay = 6,
    blipScale   = 0.6,
}

📍 Spawn Locations

⚠️ Use as few spawn locations as possible to avoid state bag rate limit issues.

Locations = {
    [1] = {
        coords = vector4(-1850.05, -700.41, 9.39, 122.04),
        livery = 13,
        height = 350,
        idle   = 75000,
        move   = 90000,
        tick   = 50,
        blip   = false,
        color  = 69
    },
    [2] = {
        coords = vector4(1579.03, 3749.89, 34.15, 29.34),
        livery = 13,
        height = 350,
        idle   = 75000,
        move   = 90000,
        tick   = 50,
        blip   = true,
        color  = 17
    }
}

---

🚀 Installation

1. Add Dependencies

Ensure these two resources are in your resources directory:

• ox_lib

• xmmx_bridge

Ensure ox_lib is initialized in your server config:

ensure ox_lib

2. Add This Resource

Place the xmmx_hotairballoons folder in your resources directory and start it after the dependencies:

ensure xmmx_bridge
ensure xmmx_hotairballoons

3. Verify Configuration

Open config.lua and:

• Adjust balloon model if custom

• Add/remove spawn locations

• Tune idle, move, and height values

• Match animation dict/clip with available emotes if customized

---

💬 Locales

The Locales table is where you customize all the text for notifications, menus, targets, etc.:

Locales = {
    waiting = "Waiting for a passenger...",
    lift_off_in = "Lift Off In: %s second(s)",
}

---

🧪 Testing

Once installed, restart your server, and ensure:

• Hot air balloons spawn at configured locations

• Players can interact and enter

• Balloons ascend, idle, and descend as expected

• State updates appear in debug if enabled

---

❓ Troubleshooting

• Balloon doesn't spawn?

  • Make sure you're the first player to connect (spawns only once)

  • Check logs for [XMMX-DEBUG] output

  • Ensure model "balloon" exists or is streamed properly

• State bag warnings in console?

  • Too many spawn locations or frequent updates

  • Reduce number of locations

  • Uses SetStateIfChanged optimization (already included)

---