Config Settings

Everything a server owner needs lives in shared/config.lua, a short file with a comment on every line. Internal values (prop offsets, animation clips, voice presets, flight physics, screen effects) live in shared/internal.lua and do not need to be touched for a normal install.

Change a value, save, ensure frkn-helium. No database, nothing else to edit.

General#

Language = "en",

Nine languages ship with the resource: ar de en es fr it pt ru tr. To add your own, copy a file in locales, rename it to your code, translate the values and set Language to that code. Keep the %s / %d placeholders where they are.

Items#

Gases = {
    { id = "helium", balloonItem = "helium_balloon", pitchCents = 700 },
    { id = "sf6",    balloonItem = "sf6_balloon",    pitchCents = -600 },
},

Tank = {
    item = "helium_tank",
    capacity = 1000,
    fillTime = 7000,
    removeWhenEmpty = true,
    pickupAnyone = false,
    maxPerPlayer = 3,
},

Option	Description
`Gases[].id`	Internal id, `helium` and `sf6` come with models, clips and voices already set up. Do not rename an id once players own balloons
`Gases[].balloonItem`	Balloon item name in your inventory
`Gases[].pitchCents`	Voice pitch. Positive raises the voice (helium), negative lowers it (SF6). `1200` is one octave
`Tank.item`	The single tank item. It refills whichever balloon the player is holding, so one tank serves every gas
`Tank.capacity`	Gas inside a new tank. `1000` fills ten empty balloons
`Tank.fillTime`	Refill duration in ms
`Tank.removeWhenEmpty`	`true` deletes the tank when it runs dry, `false` lets the owner pick it up empty
`Tank.pickupAnyone`	`true` lets anyone take a placed tank, `false` only the player who placed it
`Tank.maxPerPlayer`	How many tanks one player can have on the ground at once

Delete the sf6 line if you only want helium. Placed tanks are not saved, a restart removes them.

Every balloon and the tank must be unique / stack = false items. The gas amount is stored per item in metadata and shows as the inventory quality bar.

Balloon#

Balloon = {
    gasPerInhale = 25,
    inhaleTime = 5000,
    voiceDuration = 60000,
},

Release = {
    enabled = true,
    sfx = true,
    sfxVolume = 1.0,
},

Option	Description
`gasPerInhale`	Gas used per breath, `25` means four breaths per full balloon
`inhaleTime`	Length of one breath in ms
`voiceDuration`	How long the voice effect lasts after each breath. It stacks, a second breath adds to the remaining time. The HUD shows the countdown
`Release.enabled`	`R` lets the balloon go: it flies off in spirals, deflates and the item is removed
`Release.sfx` / `sfxVolume`	The escaping air sound (a real CC0 recording in `html/sfx`) and its volume

Overdose#

Overdose = {
    perInhale = 34,
    decayPerSecond = 1.2,
    dizzyAt = 30,
    heavyAt = 60,
    faintAt = 90,
    faintDuration = 5000,
    faintDamage = 5,
},

Every breath adds perInhale dose, dose fades by decayPerSecond each second. With the defaults three quick breaths black a player out while spaced out breaths stay harmless.

Stage	Reached at	What happens
Dizzy	`dizzyAt`	Light screen sway, slightly drunk walk
Heavy	`heavyAt`	Strong sway, motion blur, very drunk walk, random stumbles
Blackout	`faintAt`	Screen fades, ragdoll for `faintDuration` ms, loses `faintDamage` health, drops the balloon

Dose is tracked server side, so it cannot be faked.

Voice#

Voice = {
    requireMic = true,
    range = 20.0,
    scaleByDose = true,
},

Option	Description
`requireMic`	`true` means a balloon can only be used once the player has allowed microphone access, so everyone is heard with the real pitch shift. Using the balloon before that opens the F8 prompt and retries automatically once allowed. `false` lets refusers use balloons with a weaker in game effect
`range`	Hearing distance of the pitched voice in meters, keep it close to your voice script proximity
`scaleByDose`	First breath is a lighter shift, near blackout is the full `pitchCents`

The Voice System page explains how the pitch shift works and what to put in server.cfg.

Controls & HUD#

Keys = {
    inhale = 38,          -- E
    pose = 47,            -- G
    stow = 73,            -- X
    release = 45,         -- R
    place = 191,          -- ENTER
    cancel = 73,          -- X
    fallbackFill = 38,    -- E
    fallbackPickup = 74,  -- H
},

Hud = {
    mode = "textui",
    textUiPosition = "right-center",
    voiceTimer = true,
    voiceTimerWhenIdle = true,
},

Option	Description
`Keys`	FiveM control ids, the full list is on the Cfx docs. `fallbackFill` / `fallbackPickup` are only used without ox_target or qb-target
`Hud.mode`	`"textui"` uses ox_lib TextUI, `"native"` draws a box in game
`Hud.voiceTimer`	Shows how long the voice effect still lasts
`Hud.voiceTimerWhenIdle`	Keeps showing it after the balloon is stashed. It steps aside whenever another script opens its own TextUI
`HandsUpFix`	Most servers bind `X` to hands up through `RegisterKeyMapping`, which a script cannot block. This cancels that animation right after the balloon is stashed. Turn it off if nothing on your server shares `X`

Advanced: `shared/internal.lua`#

Everything else is in shared/internal.lua: balloon and tank models, hand / mouth / tank offsets, the inflation clip and its gas keyframes, the player animations, the flight of a released balloon, the sound file, the screen effects of each overdose stage, the fallback voice presets and the per gas defaults. The file has no comments on purpose, it is the engine room. Change it only if you know what you are doing, the defaults were tuned for the models that ship with the resource.