Big Daddy AirDrop

Requirements

FiveM with OneSync enabled
A running ox_inventory or qb-inventory installation and its required dependencies
Inventory definitions for every reward item and the configured flare item

Targeting is optional. No database setup is required by AirDrop. Keep the supplied DLLs, licensing helper and NUI files together in the resource folder. The included configuration uses custom inventory item names; those items must exist in your inventory or be replaced with your own names.

Installation

Copy the supplied BigDaddy-AirDrop resource 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.
Start your framework, inventory and optional targeting resources before AirDrop.
Add ensure BigDaddy-AirDrop to server.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. Changes to settings.ini or config.json require a resource restart.

Administrator permission

Permissions are configured under the existing [settings] section of settings.ini. Keep your other settings and license values intact.

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 admin commands without an ACE grant. License validation is still required. Console commands are permitted in either permission mode.

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	Use `item.drop.crates` at your current position, without consuming a flare
`/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 position. Zone numbers start at 1 and follow array order.

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 18 metres apart along the flight path. Wind drifts each crate 8?15 metres during descent, with a shared direction and small per-crate variation. 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.

Drops operate in routing bucket 0, the main world. Players joining during a drop receive its current stage and remaining loot. Resource restarts clear drops; they are not saved between sessions.

Customizing config.json

Edit the config.json inside the resource folder. 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": "Airdrop Flare",
  "flareProp": "prop_flare_01b",
  "cooldown": 60,
  "drop": {
    "flare": true,
    "crates": ["food1", "water", "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": ["food1", "water"]
}

To add a zone, append another object to the drops array, separated by a comma. 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 supplied types are food1, food2, water, weapons, snacks and energy. 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[].chance is 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[].chance is 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. 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.

A trusted server resource may call exports['BigDaddy-AirDrop']:UseFlare(source). This returns whether the throw request was accepted, not whether the flare has landed. It applies the same player, item, cooldown and active-drop checks; item consumption and drop creation occur later, after the server verifies landing. Flare exports are registered only when the resource is licensed and item.enabled=true.

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.
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.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search