Configuration

All configuration lives in configuration/index.lua. This file is not escrow-locked — you can edit it freely.

Debug & Theme

Config.Debug = false
Config.Theme = '#8290F8'

Key	Type	Default	What it does
`Config.Debug`	boolean	`false`	Enables verbose console output. Disable in production.
`Config.Theme`	string	`'#8290F8'`	Hex color used for Discord webhook embeds.

Auto Airdrop

Config.AutoAirdrop = {
    Enabled        = false,
    Interval       = 900,
    PrizePool      = 'Standard',
    RandomLocation = true,
    Radius         = 80.0,
}

Key	Type	Default	What it does
`Enabled`	boolean	`false`	Automatically spawns airdrops on a timer when `true`.
`Interval`	number	`900`	Seconds between automatic airdrops. `900` = 15 minutes.
`PrizePool`	string	`'Standard'`	Name of the prize pool used for automatic drops. Must match a key in `Config.PrizePools`.
`RandomLocation`	boolean	`true`	If `true`, picks a random location from `Config.Locations` each drop. If `false`, cycles through them in order.
`Radius`	number	`80.0`	Radius (metres) of the landing zone circle shown on the map.

Expiry

Config.Expiry = 1800

Key	Type	Default	What it does
`Config.Expiry`	number	`1800`	Seconds before an uncollected airdrop expires and is removed. `1800` = 30 minutes.

Crate

Model

Config.Crate = {
    Type = 'static',
 
    Model = {
        Crate     = 'cs_airdrop_crate_l',
        Parachute = 'cs_airdrop_parachute_l',
    },
 
    FallbackModel = {
        Crate     = 'prop_box_wood02a',
        Parachute = 'p_parachute1_mp_dec',
    },
    ...
}

Key	Type	Default	What it does
`Config.Crate.Type`	string	`'static'`	`'static'` always uses `Config.Crate.Model`. `'dynamic'` picks a model based on the number of items in the drop (see Dynamic below).
`Config.Crate.Model.Crate`	string	`'cs_airdrop_crate_l'`	Custom crate model (streamed with the resource).
`Config.Crate.Model.Parachute`	string	`'cs_airdrop_parachute_l'`	Custom parachute model (streamed with the resource).
`Config.Crate.FallbackModel.Crate`	string	`'prop_box_wood02a'`	Vanilla GTA model used if the custom model fails to load.
`Config.Crate.FallbackModel.Parachute`	string	`'p_parachute1_mp_dec'`	Vanilla GTA model used if the custom parachute fails to load.

Dynamic Sizing

Config.Crate.Dynamic = {
    { minItems = 1, crate = 'cs_airdrop_crate_s', parachute = 'cs_airdrop_parachute_s' },
    { minItems = 4, crate = 'cs_airdrop_crate_m', parachute = 'cs_airdrop_parachute_m' },
    { minItems = 8, crate = 'cs_airdrop_crate_l', parachute = 'cs_airdrop_parachute_l' },
}

Only applies when Config.Crate.Type = 'dynamic'. The crate with the highest minItems value that is still ≤ the actual item count is chosen.

Fall Physics

Config.Crate.SpawnHeight = 420.0
 
Config.Crate.Fall = {
    Duration       = 120000,
    VisualDistance = 900.0,
    EasePower      = 1.85,
    FinalHover     = 2.5,
    SpeedTop       = 2.5,
    SpeedLand      = 1.0,
    EaseWindow     = 25.0,
    SnapDist       = 0.25,
}

Key	Type	Default	What it does
`SpawnHeight`	number	`420.0`	Altitude (metres above ground) where the crate spawns.
`Fall.Duration`	number	`120000`	Time in milliseconds for the crate to fall from spawn height to ground. `120000` = 2 minutes.
`Fall.VisualDistance`	number	`900.0`	Distance in metres at which the crate becomes visible to players.
`Fall.EasePower`	number	`1.85`	Controls the easing curve of the descent. Higher = slower start, faster finish.
`Fall.FinalHover`	number	`2.5`	Height above ground at which the crate begins its final slow hover before landing.
`Fall.SpeedTop`	number	`2.5`	Maximum fall speed (m/s) at the fastest point of descent.
`Fall.SpeedLand`	number	`1.0`	Fall speed (m/s) during the final hover phase.
`Fall.EaseWindow`	number	`25.0`	Height range (metres) over which the easing transition applies.
`Fall.SnapDist`	number	`0.25`	Distance from ground at which the crate snaps to its final landing position.

Open

Interaction

Config.Open = {
    Distance  = 3.5,
    Key       = 'E',
    CancelKey = 'X',
    Time      = 5,
    ...
}

Key	Type	Default	What it does
`Distance`	number	`3.5`	How close (metres) a player must be to interact with the crate.
`Key`	string	`'E'`	Key to start opening the crate (key-press interaction mode).
`CancelKey`	string	`'X'`	Key to cancel the opening animation.
`Time`	number	`5`	Seconds the opening animation takes.

Required Item

Config.Open.Required = {
    Enabled = false,
    Item    = 'crowbar',
}

Key	Type	Default	What it does
`Enabled`	boolean	`false`	If `true`, players must have the specified item in their inventory to open the crate. The item is consumed on open.
`Item`	string	`'crowbar'`	The inventory item name required to open the crate.

Animation

Config.Open.Animation = {
    dict = 'missheist_jewel',
    anim = 'smash_case',
    bone = 57005,
    prop = 'w_me_crowbar',
}

The animation played while the crate is being opened. Uses standard FiveM animation dict/name format.

Interaction Mode

Config.Interaction = {
    mode        = 'target',
    targetIcon  = 'fa-solid fa-parachute-box',
    targetLabel = 'Open Airdrop',
}

Key	Type	Default	What it does
`mode`	string	`'target'`	`'target'` uses ox_target for interaction. `'key'` uses the key defined in `Config.Open.Key`.
`targetIcon`	string	`'fa-solid fa-parachute-box'`	Font Awesome icon shown in the ox_target prompt (only used when `mode = 'target'`).
`targetLabel`	string	`'Open Airdrop'`	Label shown in the ox_target prompt.

Admin Permissions

Config.Admin = {
    Mode            = 'both',
    AcePermission   = 'pyra.airdrops',
    FrameworkGroups = { 'admin', 'superadmin', 'god' },
}

Same structure as Pyra Reports. See Reports — Configuration: Admin Permissions.

Key	Type	Default	What it does
`Config.Admin.Mode`	string	`'both'`	`'ace'`, `'framework'`, or `'both'`.
`Config.Admin.AcePermission`	string	`'pyra.airdrops'`	ACE node checked for admin access.
`Config.Admin.FrameworkGroups`	table	`{ 'admin', 'superadmin', 'god' }`	Framework groups that grant admin access.

Zone

Outside Damage Protection

Config.Zone.OutsideDamageProtection = {
    Enabled                   = true,
    ClientRepair              = true,
    DisableOutsideFiring      = true,
    DisablePlayerFiringNative = true,
    Statuses = {
        dropping = true,
        landed   = true,
        opening  = true,
    },
}

Prevents players outside the drop zone from shooting into it. Statuses controls which crate states are protected.

Key	Type	Default	What it does
`Enabled`	boolean	`true`	Master toggle for outside damage protection.
`ClientRepair`	boolean	`true`	Repairs vehicle damage caused by shots from outside the zone.
`DisableOutsideFiring`	boolean	`true`	Prevents players outside the zone from firing toward it.
`DisablePlayerFiringNative`	boolean	`true`	Disables the native firing flag for players outside the zone.
`Statuses.dropping`	boolean	`true`	Protection active while the crate is falling.
`Statuses.landed`	boolean	`true`	Protection active after the crate has landed.
`Statuses.opening`	boolean	`true`	Protection active while a player is opening the crate.

Zone Marker

Config.Zone.Marker = {
    Enabled = true,
    Type    = 28,
    Color   = { r = 130, g = 144, b = 248, a = 120 },
    Height  = 50.0,
    Scale   = 1.0,
}

Key	Type	Default	What it does
`Enabled`	boolean	`true`	Shows a 3D marker column above the landing zone.
`Type`	number	`28`	FiveM marker type ID. `28` is a vertical cylinder beam.
`Color`	table	`{ r=130, g=144, b=248, a=120 }`	RGBA color of the marker.
`Height`	number	`50.0`	Height of the marker column in metres.
`Scale`	number	`1.0`	Width multiplier of the marker.

Config.Zone.DefaultRadius = 50.0

Key	Type	Default	What it does
`Config.Zone.DefaultRadius`	number	`50.0`	Radius of the landing zone in metres. Used for damage protection and marker sizing.

Blip

Config.Blip = {
    Enabled     = true,
    Sprite      = 119,
    Color       = 1,
    Scale       = 1.0,
    Label       = 'Airdrop',
    ShowOnSpawn = true,
    ShowRadius  = true,
    RadiusColor = { r = 130, g = 144, b = 248, a = 80 },
}

Key	Type	Default	What it does
`Enabled`	boolean	`true`	Shows a map blip for each active airdrop.
`Sprite`	number	`119`	GTA blip sprite ID.
`Color`	number	`1`	GTA blip color index.
`Scale`	number	`1.0`	Size of the blip on the map.
`Label`	string	`'Airdrop'`	Text shown when hovering over the blip.
`ShowOnSpawn`	boolean	`true`	Blip appears when the crate spawns (before landing).
`ShowRadius`	boolean	`true`	Shows a translucent radius circle around the drop zone on the map.
`RadiusColor`	table	`{ r=130, g=144, b=248, a=80 }`	RGBA fill color for the radius circle.

Notifications

Config.Notifications = {
    Spawn = {
        Enabled     = true,
        Message     = 'Airdrop deployed',
        Description = 'A crate is parachuting down — check your map for the drop zone.',
        Type        = 'info',
        Duration    = 5000,
    },
    Expire = {
        Enabled     = true,
        Message     = 'Airdrop expired',
        Description = 'Nobody collected the crate in time. Better luck next drop.',
        Type        = 'warning',
        Duration    = 4000,
    },
    Collected = {
        Enabled     = true,
        Message     = 'Airdrop collected',
        Description = 'Loot has been added to your inventory. Stay sharp out there.',
        Type        = 'success',
        Duration    = 5000,
    },
}

Each notification supports:

Key	Type	What it does
`Enabled`	boolean	Show or hide this notification type.
`Message`	string	Title line of the notification.
`Description`	string	Body text of the notification.
`Type`	string	Notification style: `'info'`, `'warning'`, `'success'`, or `'error'`.
`Duration`	number	How long the notification stays on screen in milliseconds.

Items

The Config.Items table defines every possible item that can appear in any prize pool. Only items listed here can be added to prize pools.

Config.Items = {
    ['money'] = { label = 'Cash', min = 100, max = 25000 },
    -- ...
}

Key	Type	What it does
`label`	string	Display name shown in the admin panel and Discord webhook.
`min`	number	Minimum quantity given when this item is rolled.
`max`	number	Maximum quantity given when this item is rolled.

The item key must match your inventory system's item name exactly (e.g. 'money', 'WEAPON_PISTOL').

Prize Pools

Config.PrizePools = {
    ['Standard'] = {
        { item = 'money',    label = 'Cash',       amount = 5000 },
        { item = 'firstaid', label = 'First Aid',  amount = 2    },
        { item = 'armour',   label = 'Body Armor', amount = 1    },
    },
    ['Heavy Weapons'] = { ... },
    ['Contraband']    = { ... },
}

Each prize pool is a named list of items. All items in the pool are given when the crate is opened — there is no random selection between pool entries.

Key	Type	What it does
`item`	string	Must match a key in `Config.Items`.
`label`	string	Human-readable name shown in logs and the admin panel.
`amount`	number	Fixed quantity given. A random amount between `Config.Items[item].min` and `Config.Items[item].max` is given if you omit `amount` in future versions.

The pool name (e.g. 'Standard') is what you enter in Config.AutoAirdrop.PrizePool and in the admin manager when spawning a manual drop.

Locations

Config.Locations = {
    ['Legion Square'] = { x = -267.0, y = -963.0 },
}

Named map coordinates used for automatic airdrops. Add as many as you like. Each entry needs only x and y — the crate always spawns at Config.Crate.SpawnHeight above ground regardless of z.

Key	Type	What it does
Key (string)	string	Name shown in the admin panel location picker.
`x`	number	World X coordinate of the drop zone centre.
`y`	number	World Y coordinate of the drop zone centre.

Installation Commands