AirDrop
POPULAR LINKS
{:links-list}
Requirements
- FiveM with OneSync enabled
- A running
ox_inventoryorqb-inventoryinstallation and its required dependencies - Inventory definitions for every reward item and the configured flare item
- Game assets for the selected aircraft and prop models
Targeting is optional. No database setup is required by AirDrop.
Installation
- Copy the supplied
BigDaddy-AirDropresource folder into your server's resources directory. Keep that exact folder name. - Configure the issued licensing values in
settings.ini. - Customize
config.json, particularly the inventory items and drop locations. THERE IS AN IN-GAME EDITOR FOR THIS (see below) - Start your framework, inventory and optional targeting resources before AirDrop.
- Add
ensure BigDaddy-AirDroptoserver.cfg.
Example resource order with ox inventory and targeting, after their dependencies:
ensure ox_inventory
ensure ox_target
ensure BigDaddy-AirDrop
Use your selected providers' resource names instead when using QB inventory or targeting. The in-game editor saves and applies gameplay settings when idle, without restarting. Restarting clears the active drop and remaining loot.
Administrator permission
Permissions are configured under the [settings] section of settings.ini.
UseAcePermissions=true
AcePermission=bigdaddy.airdrop.admin
For this example, grant the same ACE in server.cfg:
add_ace group.admin bigdaddy.airdrop.admin allow
Players must already belong to the permitted group through your server's principal assignments. Setting UseAcePermissions=false allows players to use the drop-management commands without an ACE grant. The configuration editor always requires the configured AcePermission, including when UseAcePermissions=false. License validation is still required. Console can manage drops in either permission mode; opening the editor requires an in-game player.
Inventory flare use does not require administrator ACE access. It requires an enabled flare feature, a valid player, a flare item, an available drop slot and an expired cooldown.
Commands
The table uses the command names in the supplied configuration.
| Command | Access | Purpose |
|---|---|---|
/airdrop |
Admin permission when enabled | Start a drop at a random configured zone |
/airdrop 2 |
Admin permission when enabled | Start a drop at the second entry in drops |
/airdrop here |
Admin permission when enabled | Start a drop at your current position, without consuming a flare |
/airdrop config |
Configured ACE always required | Open the guided configuration editor with inventory item search |
/airdrop status |
Admin permission when enabled | Show whether a drop is active and its cleanup countdown |
/airdrop cancel |
Admin permission when enabled | Remove the active aircraft, cargo, loot and markers |
here requires a player who is alive in the main world. config requires an in-game player. Console commands omit the /. Zone numbers start at 1 and follow array order. Changing command changes the base name for all these commands.
In-game configuration editor
Run /airdrop config after licensing completes, using a player with the ACE configured in settings.ini. The editor has General, Aircraft, Flare calls, Drop zones, and Crates & loot sections. It can edit schedules, aircraft settings, flare calls, zone positions and optional names, crate types, pickup props, animations and inventory rewards. Position buttons use your current coordinates; duplicate controls copy crate types and pickup packages.
Search inventory rewards by registered item name or label. The editor reads the selected inventory provider's catalog; it does not create inventory items. GTA prop model names are separate from inventory item names. Saving requires a running supported inventory and rejects unknown reward items and an unknown flare item when flare calls are enabled. QB inventory item discovery requires qb-core; Qbox with ox inventory uses the ox catalog.
Each successful save validates the configuration, checks whether the file changed since it was loaded, creates a timestamped config.json.*.bak beside the configuration file, and verifies the write. Changes apply immediately when idle. During an active drop or pending flare throw, they wait until that activity clears, including the drop's remaining loot lifetime. Applying settings resets the automatic-drop countdown. If you change command, use the new command name after the settings apply. Changing the flare inventory key also requires updating its inventory item integration.
Close with Escape or Close. Unsaved edits prompt you to keep editing or discard them. Reload reads the current file and inventory catalog; after a conflicting edit, close and discard your unsaved changes, then reopen to load the latest file. Backups can be restored manually while the resource is stopped. ACE and licensing settings remain in settings.ini and require a restart after direct edits.
An easy way to think about this setup is there are drop types, and in the drop types are one or more drop packages. In the drop packages are one or more inventory items. Then you can assign those types to drop zones and flare initiated drops.
How drops work
Only one drop or pending flare throw may be active at a time, including the remaining loot lifetime of an existing drop. Automatic, admin and flare requests share this limit. Collecting all supplies does not end the timer early; /airdrop cancel clears the drop immediately.
Automatic drops count players with available ped positions in the main world (routing bucket 0) inside each configured zone's horizontal radius when the timer expires. They choose the zone containing the most players, breaking equal-count ties randomly. If every zone is empty, all zones are tied and one is selected randomly. Overlapping zones each count players inside them. After selecting the zone, the system chooses a random starting point within its radius. Manual /airdrop commands without a zone number still select a random zone. The aircraft's flight direction is randomized. Crates follow the order of the zone's crates list. Their release points are spaced apart along the flight path. Wind drifts each crate during descent. Loot and delivery markers use the resulting landing sites. The zone radius selects the first release point; it is not a boundary containing every crate and pickup prop.
The aircraft keeps the configured flight speed. Cargo descends for approximately 20 seconds with p_cargo_chute_s attached above it. Plane and crate markers are controlled separately. Ground flare effects appear only for definitions with flare=true.
Customizing config.json
We absolutely recommend using the in-game editor to edit the config instead of manual editing. You CAN edit it manually but it needs to be valid and accurate.
Keep double quotes around keys and text, use lowercase true and false, and do not add comments or trailing commas. The examples below replace the corresponding section or entry; they are not complete replacement configurations unless explicitly stated.
General settings
| Setting | Supplied value | Description |
|---|---|---|
inventory |
"auto" |
auto, ox_inventory or qb-inventory. Auto prefers a running ox inventory. A supported inventory is required for drops. |
target |
"auto" |
auto, none, ox_target or qb-target. Auto prefers ox targeting. The key prompt remains available without targeting. |
command |
"airdrop" |
Admin command name, without / or spaces. |
interactionKey |
38 |
FiveM control index for collecting nearby supplies; allowed range 0–360. |
interactionKeyLabel |
"E" |
Text displayed in the interaction prompt. Change this together with the control index. |
minimumPlayers |
1 |
Connected-player count required for automatic drops, 1–2048. Does not restrict manual or flare drops. |
announce |
true |
Broadcast an inbound supply-aircraft notification when a drop starts. |
debug |
false |
Display configured automatic-zone circles on the map. |
Automatic drops
{
"enabled": true,
"timeBetweenDrops": 30
}
Replace automaticDrop with this object for a drop opportunity every 30 minutes. The interval starts after successful startup; the first drop is not immediate. If a drop is still active, too few players are connected, or no supported inventory is running, that opportunity is skipped and the next interval remains scheduled.
timeBetweenDrops accepts 0.1–10080 minutes. Set enabled=false to stop automatic drops while retaining manual and enabled flare drops.
Aircraft
{
"model": "titan",
"flightSpeed": 60,
"color": { "r": 30, "g": 40, "b": 0 }
}
Replace plane with this object. model must name an available aircraft model. flightSpeed is metres per second, from 20–100. Color channels are integers from 0–255 and apply to the aircraft's custom primary and secondary colors.
The 18-metre release spacing remains the same when speed changes; faster aircraft release crates closer together in time. Flight height, parachute model and descent duration are built-in behavior, not configuration fields.
Timers and blips
| Setting | Supplied value | Unit and behavior |
|---|---|---|
misc.dropLifetime |
10 |
Minutes after the final crate lands before the entire drop is removed. Range 0.1–1440. |
misc.flareLifetime |
120 |
Seconds each ground flare remains after its crate lands. Range 0–86400; 0 disables the effect. |
misc.planeBlips |
true |
Show the aircraft marker during its flight. |
misc.crateBlips |
true |
Show markers at delivery sites beginning at release. |
misc.crateBlipsLifetime |
120 |
Seconds crate markers remain after landing. Range 0–86400. Zero still permits markers during descent. |
Overall drop cleanup removes all remaining effects and markers even if their individual timers are longer.
Player-called drops
{
"enabled": true,
"flareItemName": "prop_flare_01b",
"flareProp": "prop_flare_01b",
"cooldown": 60,
"drop": {
"flare": true,
"crates": ["food", "weapons"]
}
}
Replace item with this object. cooldown is seconds per player, from 0–86400, beginning when a flare call succeeds. The active-drop limit also applies. Cooldowns survive reconnecting during the current resource session and reset on resource restart.
flareItemName must match an inventory item. The optional flareProp selects the physical hand/thrown prop model. If omitted, the model uses flareItemName too, so your current prop_flare_01b value is used for both. When the inventory key differs from the model name, set flareProp explicitly as in the example. Selecting the item closes the inventory, places a flare prop in the player's hand and immediately plays an underhand toss. The flare moves with game physics. Once the server verifies that it has settled, one item is consumed and the drop is called to that location. Failed, cancelled or timed-out throws do not consume the item. Rejected overlap or cooldown requests do not begin a throw. item.drop.flare controls the ground flare effect, and item.drop.crates selects the delivery types. The thrown flare's settled position supplies the location; adding coords or radius here does not relocate flare calls. Throw while alive and on foot in the main world. Stay nearby until the landing is accepted. Escape cancels a pending throw. The flare must settle within 30 horizontal metres of the throw origin and within the supported height range (20 metres below to 5 metres above it); avoid cliff edges and water. A throw times out after 25 seconds. The physical signal remains for misc.flareLifetime seconds after acceptance.
/airdrop here also uses this composition, even when item.enabled=false, but does not consume the item or apply its cooldown. Keep the item section valid even when flare use is disabled.
Drop locations
Each object in drops defines one automatic/manual zone:
{
"coords": { "x": 1929.8, "y": 3332.1, "z": 45.5 },
"radius": 100,
"flare": true,
"crates": ["food", "weapons"]
}
To add a zone, append another object to the drops array, separated by a comma. An optional name labels the zone in the editor; zone commands still use array numbers. Set coords to the outdoor delivery area's center and approximate ground elevation. Coordinates accept values from -20000 to 20000. radius is in metres, from 0–2000; 0 uses the exact center for the first delivery site.
Every name in crates must exactly match a key in types. At least one zone is required, including when automatic drops are disabled. Keep the total crate count at or below 30 for each drop definition, counting type repetitions.
Use open, reasonably level ground. Avoid water, buildings and steep terrain. Allow room around the zone for the full row of crates and scattered loot. Use debug=true to inspect zone circles and /airdrop <number> to test each zone.
Crate types and loot
The default configuration defines two types, food and weapons, used by all five supplied zones and by flare calls. Your inventory must contain their configured reward items. A type has three separate quantities:
| Field | Meaning | Range |
|---|---|---|
types.<name>.amount |
Number of large delivery crates for each appearance of this type in a drop list | 1–10 |
types.<name>.loot.amount |
Number of small collectible props generated per delivery crate, subject to spacing | 1–50 |
items[].amount.min / max |
Inventory quantity for a successful reward roll in one collectible prop | 1–100000; max must be at least min |
For example, two delivery crates with eight loot props each create up to 16 collectible props. Reward quantities are rolled for each prop independently.
| Type field | Description |
|---|---|
model |
Large delivery-crate prop model. |
chunks |
Retained for compatibility; currently unused. Landing debris comes from a particle effect, not separately spawned fragment props. |
loot.radius |
Loot scattering radius around each crate in metres, 0.5–50. |
loot.loot |
List of possible collectible-prop definitions. |
Each entry inside loot.loot supports:
| Field | Description |
|---|---|
hash |
Prop model name for the small collectible package. This is separate from the inventory item name. |
chance |
Relative selection weight, 0–100. At least one entry in the type must have a positive weight. |
textureVariation |
Model texture variation index, 0–255. The model must support the selected variation. |
minimumDistanceBetween |
Minimum spacing between loot props from the same crate, in metres, 0–50. |
offset.x, offset.y, offset.z |
World-axis offsets in metres, each from -20 to 20. Z is applied after aligning the model's bottom with the ground. |
labelSingular, labelPlural |
Names used in collection notifications. The legacy spelling labelPlurar is also accepted when labelPlural is absent. |
collectMessage |
Text used by the key prompt and target option. |
icon |
Icon string passed to the targeting provider, such as fas fa-box. |
animation |
Pickup animation settings for this particular prop. |
items |
Inventory rewards that may be contained in this prop. |
If the scatter radius cannot fit all props at the requested spacing, fewer props are generated and the server logs the affected type. Increase the radius or reduce the spacing/count.
Loot weights versus reward chances
The two chance fields do different jobs:
- Prop selection:
loot.loot[].chanceis a relative weight. Two entries weighted 70 and 30 are selected approximately 70% and 30% of the time. A single entry with weight 70 is selected every time because there is no competing entry. - Inventory rewards:
items[].chanceis an independent percentage from 0–100. Every item entry is rolled separately. A prop can contain several rewards or no rewards. Set an item's chance to 100 to guarantee that entry.
items[].item must be the exact registered inventory item name. Its amount is chosen inclusively between min and max. Duplicate item entries produce separate rolls; remove duplicates if you do not intend extra opportunities for that reward.
Example: add a guaranteed water package
Add the following water_package entry inside types, separating it from existing entries with a comma. Replace water_bottle with the actual water item name used by your inventory.
{
"water_package": {
"amount": 1,
"model": "prop_lev_crate_01",
"chunks": "prop_ld_crate_lid_01",
"loot": {
"amount": 4,
"radius": 5,
"loot": [
{
"hash": "prop_lev_crate_01",
"chance": 100,
"textureVariation": 0,
"minimumDistanceBetween": 2,
"offset": { "x": 0, "y": 0, "z": 0 },
"labelSingular": "Water Bottle",
"labelPlural": "Water Bottles",
"collectMessage": "Collect the water",
"icon": "fas fa-box",
"animation": {
"dict": "mp_take_money_mg",
"anim": "put_cash_into_bag_loop",
"duration": 2,
"flag": 1
},
"items": [
{ "item": "water_bottle", "chance": 100, "amount": { "min": 2, "max": 5 } }
]
}
]
}
}
}
The outer braces show a fragment of the types object. Copy its water_package property into your existing types, then add "water_package" to a zone's crates list or to item.drop.crates. Defining a type alone does not schedule it.
This example creates one large delivery crate and up to four collectible boxes. Each collectible box contains 2–5 water bottles. Choose a different hash for a smaller visual package if desired.
Pickup animations
Each loot entry's animation contains dict (animation dictionary), anim (clip name), duration (seconds, 0.1–60) and flag (nonnegative animation flag integer). The supplied animation lasts two seconds.
The top-level pickupAnimation object is currently validated but does not act as a fallback or override. Keep it valid, and change the animation object inside each affected types.<name>.loot.loot entry to change actual pickup behavior.
Escape, moving away, entering a vehicle or dying cancels collection. If inventory accepts only some rewards, those granted rewards are removed from the package and the remaining rewards stay available for another attempt.
Flare item integration
Players use the flare through their inventory. The matching inventory-item integration is required.
For ox inventory, configure the flare item to call this resource's server export. An empty client = {} block does not connect inventory use to AirDrop. A ready-to-merge definition for the current prop_flare_01b item is included in installation/ox_inventory-flare.lua:
['prop_flare_01b'] = {
label = 'Airdrop Flare',
weight = 500,
stack = true,
close = true,
consume = 0,
server = { export = 'BigDaddy-AirDrop.FlareItem' },
},
This snippet belongs in your inventory's item definitions. AirDrop removes the item itself, so keep consume=0 to avoid a second consumption path since the script removes the item when it is used. Match the item key to item.flareItemName. After editing inventory definitions, restart your server so inventory reloads the item and AirDrop registers its exports. Do not use a second client event or usable-item callback for this same integration.
For QB or Qbox, add the configured item to your framework's item definitions and make it usable. AirDrop registers its usable-item callback when qb-core or qbx_core is available. Use one item-use integration per item.
Troubleshooting
| Symptom | Check |
|---|---|
| Commands do not register | Check licensing startup and server messages beginning [BigDaddy-AirDrop] Configuration rejected:. The resource must pass both checks before gameplay starts. |
| Permission denied | Check UseAcePermissions and AcePermission in settings.ini, your matching ACE grant and principal membership. Restart after changing settings. |
| Config editor access denied | /airdrop config always requires the configured AcePermission, even with UseAcePermissions=false. Open it from an in-game player. |
| Editor cannot save | Start the supported inventory, select registered reward and enabled flare items, and check that the resource can write the configuration and its backup. If the file changed elsewhere, discard unsaved edits and reopen it. |
| Saved editor changes have not applied | Wait for the current drop's full loot lifetime or pending flare throw to clear, or use /airdrop cancel. The automatic countdown restarts when settings apply. |
| Automatic drops do not start | Check the interval, connected-player minimum, supported inventory and /airdrop status. An active loot lifetime still occupies the drop slot. |
| New type does not appear | Add its exact key to the intended crates list. For /airdrop here, change item.drop.crates. |
| Props or aircraft are missing | Confirm model names and installed game assets. Check F8 for aircraft/cargo/model loading errors. Test near the selected zone. |
| Supplies cannot be collected | Check inventory capacity and exact item definitions. You must be alive, on foot, near the prop and in the main world. |
| Package is empty | Each reward is rolled independently. Give at least one reward a chance of 100 if every package should contain something. |
| Fewer small boxes than expected | Increase loot.radius, lower minimumDistanceBetween or reduce loot.amount; check the server's spacing message. |
| Custom pickup animation does not change | Edit each loot entry's animation; the top-level pickupAnimation does not override it. |