All documentation

Paid scripts

Poggy's Balloon Taxi

Hot air balloon operators across the map: players pay a fare and an NPC pilot flies them to their waypoint, rent a balloon and fly it themselves, or buy their own and call it to the nearest road. Passengers sit properly in the basket instead of ragdolling.

  • poggy_balloonv1.7.0
  • FrameworksVORP Core, RSG Core, QBCore RedM
  • Updated26 Oct 2026

Overview#

Balloon operators stand at eight stations across the map. A player sets a waypoint, talks to an operator, pays the fare, and an NPC pilot flies them there. The pilot climbs over hills, slows on approach and lands gently. Players can also rent a balloon and fly it themselves for a set time.

Up to four passengers ride in the basket with sitting animations and an invisible floor, so nobody ragdolls or falls through. Everyone on the server sees the same seats and animations.

  • Taxi rides to any waypoint, with in-flight options: stop here, change destination, "Step On It!" (faster), change seat and disembark.
  • Rentals for a set time (1 hour by default), with a warning before the time runs out. Turn rentals on or off per station.
  • Owned balloons: buy one at any station, then press B or type /balloon to have it brought to the nearest road. Friends ride along as passengers; only the owner flies it.
  • Captain controls: move, climb, descend, boost, brake and altitude lock, with camera-relative or compass steering.
  • Eight stations with map blips: Strawberry, Rhodes, Valentine, Annesburg, Saint Denis, Blackwater, Armadillo and Tumbleweed. Add your own from /poggy.
  • English, French, Spanish and German included.
  • No menu resource needed: the station menu comes from poggy_core.

Requirements#

WhatWhy
RedM with VORP Core, RSG Core or QBCore RedMIt runs on any of the three.
poggy_core 0.14.0 or newerMoney, character checks, prompts, notifications and the station menu. It must start first.
oxmysqlSaves owned balloons in one table, poggy_balloons. It is created when the script starts; there is nothing to import.

No items. Fares, rentals and balloons are paid in cash.

Installation#

  1. Download poggy_balloon from your Cfx portal and put the folder in your server's resources folder.
  2. In server.cfg, start it after oxmysql and poggy_core:
    ensure oxmysql
    ensure poggy_core
    ensure poggy_balloon
  3. If staff should be able to spawn balloons, set up the permission (see Permissions).
  4. Restart the server.

Configuration#

Every setting can be changed in game in the /poggy settings hub under Poggy Balloon, or by hand in config.lua and translations.lua. Restart the script after a change. The hub also has three help pages: Adding a balloon station, Tuning taxi flights and rentals and Owned balloons.

Services and prices

SettingDefaultWhat it does
Taxi service on (Config.BalloonTaxi.Enabled)trueTurns taxi rides on or off. With both taxi and rentals off, no operators or blips appear.
Rentals on (Config.BalloonRental.Enabled)trueTurns rentals off at every station.
Taxi ride price (Config.BalloonTaxi.Price)3Fare for one ride, taken from the player's cash. 0 makes rides free.
Rental price (Config.BalloonRental.Price)50Price of one rental, taken from cash. A player can hold one rental at a time.
Owned balloons on (Config.Ownership.Enabled)trueBuy, Take Out and Sell at every station, the call key and /balloon. Off hides it all; balloons already bought stay saved.
Balloon price (Config.Ownership.Price)500What buying a balloon costs, taken from cash. One per character.
Sell-back share (Config.Ownership.SellBackPercent)50Percent of the price paid back when a player sells their balloon. 0 removes the Sell option.

Owned balloons (Config.Ownership)

SettingDefaultWhat it does
Command name (CallCommand)"balloon"The command that calls the balloon: /balloon, and /balloon away to put it away. Empty = no command.
Call key (CallKey)0x4CC0E2FE (B)Control hash of the key that calls the balloon. 0 = no key. Set CallKeyLabel to the key's name so messages match.
Road distance (RoadDistance)75.0 mHow close to a road or trail a player must be. Farther away, they are told they are not near a road.
Call cooldown (CallCooldownSeconds)15Seconds between calls.
Only the owner flies it (OnlyOwnerFlies)trueAnyone else who takes the captain's seat is moved out. Passengers can always ride.
Map blip (Blip)trueShows the balloon on its owner's map while it is out.

The call key does nothing for players who own no balloon, while they sit in a vehicle, or during a taxi ride.

Taxi flights (Config.BalloonTaxi)

SettingDefaultWhat it does
Cruising altitude (CruisingAltitude)80.0 mHow high above the ground the pilot flies. Raise it if balloons clip hills.
Travel speed (TravelSpeed)22.0 m/sNormal cruising speed.
"Step on it" speed (TravelSpeedFast)30.0 m/sSpeed while the passenger has Step On It! turned on.
Climb speed (AscentSpeed)5.0 m/sHow fast the taxi climbs after take-off.
Landing speed (DescentSpeed)20.0 m/sTop sink speed while landing. Lower it if landings feel rough.
Final approach distance (FinalApproachDistance)100.0 mHow far from the waypoint the pilot starts slowing down.
Arrival distance (ArrivalDistance)5.0 mHow close to the waypoint counts as arrived.
Wait for passenger to exit (ExitWaitTime)30000 msHow long the pilot waits after landing before moving the passenger out.
Rise time before despawn (DespawnRiseTime)30000 msHow long the empty balloon rises away after the ride.
Extra time before despawn (DespawnDelay)10000 msMore rising before the balloon is deleted.

Rentals and captain controls

SettingDefaultWhat it does
Rental length (Config.BalloonRental.RentalDurationMinutes)60How long a rental lasts, in minutes. When it ends the balloon is taken back.
Expiry warning (Config.BalloonRental.WarningTimeMinutes)5Minutes of warning before a rental ends.
Scripted climb (Config.Flight.ScriptedAscent)trueHolding Shift climbs, driven by the script. Keep it on: the game's own burner key does not register on current game builds.
Top climb speed (Config.Flight.AscentMax)2.5 m/sThe fastest a captain climbs while holding Shift.
Ctrl descends (Config.Flight.DescendKey)trueHolding Ctrl pushes the balloon down. Off: it only sinks on its own.
Top descend speed (Config.Flight.DescentMax)2.0 m/sThe fastest a captain descends while holding Ctrl.

The "Your balloon is ready! Rental expires in 1 hour." message is plain text. If you change the rental length, edit rental_ready under Text & language to match. The station menu already shows the real length.

Stations (Config.BalloonTaxi.Locations)

Each station has an operator position and heading, the operator's ped model (the same model flies the taxi), a balloon spawn point and heading, a map blip, and whether rentals are offered there. In /poggy → Locations → Balloon stations, press Add station, stand where the operator should be and use Use my position, then do the same on the balloon spot. Pick open, flat ground with nothing overhead for the balloon.

The shipped stations are Strawberry, Rhodes, Valentine, Annesburg, Saint Denis, Blackwater, Armadillo and Tumbleweed, all with rentals on. An operator appears when a player is within 100 metres.

Language and keys

SettingDefaultWhat it does
Language (Config.Language, in translations.lua)"en"en, fr, es or de. Missing lines fall back to English.
Taxi keys (Config.Controls)see belowControl hashes for the taxi prompts. Advanced.
Debug logging (Config.Debug.Enabled)falsePrints taxi, rental and spawn logs. Leave off on a live server.

Shipped taxi keys: Talk G, Take Off B, Change Destination R. The other prompts show their key on screen. In the shipped config Stop here and Disembark use the same control hash; give one its own key in Advanced → Taxi keys if they clash on your server. If you change the take-off key, also edit the "Press [B]" message under Text & language.

Commands#

CommandWhoWhat it does
/balloonEveryone who owns a balloonBrings your balloon to the nearest road, the same as the call key (B).
/balloon awayEveryone who owns a balloonPuts your balloon away.
/spawnballoonAdmins (see Permissions)Spawns a balloon next to you.
/spawnballoon_localEveryone, only when admins only is offSpawns a balloon next to you. It does not exist while the spawn command is admin-only.
/balloon_server_statusACE command.balloon_server_statusPrints every balloon and who sits in each seat to the server console.
balloon_taxi_server_debug toggle | status | clear <playerId>Server consoleTaxi logging, the list of active rides, and clearing a stuck ride.
balloon_rental_debug status | end <playerId>Server consoleActive rentals with time left, or end one early.
/balloon_taxi_debug, /balloon_debug_main, /balloon_debug_anim, /balloon_debug_ctrlEveryoneDebug output for taxi, seats, animations and captain controls. They only print to the F8 console of the player who types them. Levels: 0 off, 1 errors, 2 warnings, 3 info, 4 everything.

The spawn command's name is fixed at /spawnballoon; the Name setting next to it is not used.

Permissions#

Riding, renting and owning a balloon need no permission: anyone with the cash can use a station.

/spawnballoon is controlled by Config.Commands.SpawnBalloon and checked in this order:

  1. Enabled = false: nobody can use it.
  2. AdminOnly = false: everyone can use it, and /spawnballoon_local appears too.
  3. Otherwise (the default) the player needs the ACE named in AcePermission, if you set one, or must be an admin in your framework.
# with AcePermission = "command.spawnballoon" in config.lua
add_ace group.admin command.spawnballoon allow

# for /balloon_server_status
add_ace group.admin command.balloon_server_status allow

Using it in game#

Taking a taxi ride

  1. Set a waypoint on the map.
  2. Walk up to a balloon operator and press Talk (G by default).
  3. Pick Take a Ride. The fare is taken from your cash.
  4. Board the balloon within 60 seconds, or it leaves without you.
  5. Press Take Off (B by default) when you are ready.
  6. During the flight use the prompts on screen: Stop Here, Change Destination (set a new waypoint first), Step On It!, Change Seat and Disembark.
  7. After landing, get out. The pilot waits (30 seconds by default), then the balloon flies away.

Renting a balloon

  1. Talk to an operator at a station with rentals on.
  2. Pick Rent a Balloon. The price is taken from your cash.
  3. Get in as the pilot and fly anywhere until the rental ends. You are warned before it runs out.

Owning a balloon

  1. Talk to any operator and pick Buy a Balloon. The price is taken from your cash.
  2. Anywhere near a road, press B or type /balloon. Your balloon is brought to the nearest road and shown on your map.
  3. At a station, pick Take Out Your Balloon to have it brought out there instead.
  4. /balloon away puts it away. Calling it again moves it to the road nearest you.
  5. Sell Your Balloon at a station sells it back for part of what you paid.

Friends board as passengers the usual way. Only you can fly it.

Flying as captain

ControlAction
W / SForward / back
A / DLeft / right
Shift (hold)Burn and climb
Ctrl (hold)Descend
Boost prompt (hold)Move faster
Brake prompt (hold)Slow down
Lock Altitude promptHold your current height
Toggle Control Mode promptSwitch between camera-relative steering (forward is where you look) and north/south/east/west

The key for each prompt is shown on screen.

Riding as a passenger

Walk up to a balloon and hold the Enter as Passenger prompt. Up to four passengers fit in the basket.

Troubleshooting#

"Please set a waypoint on your map first."

Taxi rides fly to your waypoint. Set one before talking to the operator.

"You are already on a balloon ride." but I am not

A ride did not close properly. In the server console run balloon_taxi_server_debug clear <playerId>.

No operators or blips

Check that the taxi or rentals are turned on. An operator only appears when a player is within 100 metres of the station.

The captain cannot climb

Keep Scripted climb on (Config.Flight.ScriptedAscent = true). The game's own burner key does not register on current game builds.

A rental balloon has no controls

The captain controls only work on the hotairballoon01 model. Keep Config.BalloonRental.BalloonModel set to it.

The ready message says "1 hour" but rentals are shorter

That line is plain text: edit rental_ready in translations.lua or under Text & language.

"You're not near a road." when calling a balloon

The balloon only comes to a road or trail. Walk to one, use Take Out Your Balloon at a station, or raise Road distance.

A player was moved out of the captain's seat

That balloon belongs to someone else. Ride as a passenger, or turn Only the owner flies it off.

Taking a balloon away from a player

Delete their row from the poggy_balloons table (keyed by character id).

/spawnballoon says I have no permission

With admins only on, you need the ACE set in AcePermission or to be an admin in your framework. See Permissions.

Updating#

poggy_core's updater keeps it up to date, and your config.lua and translations.lua settings are kept: see Updates.

Updating to 1.7.0: this version adds a sql folder, and a server cannot make folders for itself. Before the update installs, run this once in PowerShell, with the path changed to your poggy_balloon folder:

New-Item -ItemType Directory -Force "C:\txData\resources\[Poggy]\poggy_balloon\sql"

Also make sure oxmysql starts before poggy_balloon in server.cfg.

Coming from the old poggy-balloon? The folder was renamed to poggy_balloon in 1.5.1. Delete the old folder, add the new one, and change ensure poggy-balloon to ensure poggy_balloon in server.cfg. The settings are the same, so copy across any values you changed.

Guides that use Poggy's Balloon Taxi

Join the Discord Discord