Black FridayVault Festival from 60 € to 35 €. Only until Cyber Monday.--d --h --m --sGet it →
VAULTSTORE
Vault Festival

For developers

Back to the index

Other scripts can control the festival with exports, and react to it with events.

All examples use the resource name vault-festival. If you renamed the folder (not recommended), use your name instead.

Server exports

Call them from a server script:

exports['vault-festival']:mount()

Most of them return two values: ok (true or false) and err (a short error code, or nil).

local ok, err = exports['vault-festival']:setTheme('spire')
if not ok then print('Could not change theme: ' .. err) end

The server exports are trusted: they do not check permissions. Check permissions yourself before calling them for a player (use isOperator or isAdmin).

Venue

Export What it does
mount() Builds the festival.
unmount() Takes it down.
isMounted() Returns true or false.
setOrigin(coords, heading?) Moves the festival. coords: a vector4, or a vector3 plus heading, or { x, y, z, w }. x and y between -20000 and 20000, z between -500 and 3000.
resetOrigin() Moves it back to Config.DefaultOrigin.
getOrigin() Returns a vector4.
setTheme(id) amphitheatre, leviathan, observatory, phoenix, clockwork or spire.
getTheme() Returns the theme id.
getThemes() Returns { { id, label }, ... }.
setIsland(enabled, vegetation?) Island on/off, and its vegetation.

Music

Export What it does
playTrack(url, startSeconds?) Plays a song for everyone. http:// or https:// link, 300 characters at most. If the song was analysed, its light show runs too.
stopTrack() Stops the music.
getTrack() Returns { url, name, position } or nil.
getSongs() Returns { { name, url, analysed, fromConfig }, ... }.
addSong(url, name?) Adds a song to the list.
removeSong(url, deleteAnalysis?) Removes a song.
renameSong(url, name) Renames a song.

Songs in the music/ folder have this URL: https://cfx-nui-vault-festival/music/<file>. Use getSongs() to get it.

Lights and effects

Export What it does
setMode(mode) 'auto', 'live' or 'hybrid'.
setMaster(value) Overall brightness, 0.0 to 1.0.
setScene(scene) A scene index, a scene id, or false to clear. In Auto mode it switches to Hybrid.
setPalette(index) Palette 1 to 8, or false to clear. In Auto mode it switches to Hybrid.
getScenes() Returns { { index, id, label, category }, ... }. Pass the id (or index) from here to setScene.
getPalettes() Returns { { index, name }, ... }.
setBlackout(on) true or false.
setArmed(on) Arms or disarms the pyro.
fire(effect, force?) Fires an effect (list below). Pyro needs to be armed, unless force is true. The cooldown always applies.

Effects for fire: flames, co2, sparks, comets, fireworks, confetti (pyro) and smoke, low_fog, smoke_jets, streamers, bubbles, flash.

Status

getState() returns a table:

{
    mounted = true,
    theme = 'amphitheatre',
    origin = vector4(...),
    island = { enabled = true, vegetation = true },
    track = { url = '...', name = '...', position = 83.2 },  -- or nil
    mode = 'auto',
    master = 1.0,
    blackout = false,
    scene = false,     -- or the scene id (as in getScenes())
    palette = false,   -- or the palette index
    armed = false,
    playersNearby = 12,
}

Players and permissions

Export What it does
isOperator(src) true if the player can operate. src is the player’s server ID (number or text, as GetPlayers() gives).
isAdmin(src) true if the player is a festival admin.
grantOperator(src, minutes) Temporary operator access, 1 to 1440 minutes.
revokeOperator(src) Removes temporary access.
openConsole(src) Opens the console for that player. Only if they are an operator. Returns true or false.
openAdmin(src) Opens the admin panel for that player. Only if they are an admin.
giveWristband(src, type) Gives a 'general' or 'vip' wristband, free.
hasWristband(src, type?) true if they have it. A VIP wristband also counts as general.

Error codes

Code Meaning
invalid_argument A value is wrong or out of range.
unknown_theme That theme does not exist.
cooldown Too fast. Try again in a moment.
not_armed Pyro is not armed.
invalid_url The link must start with http:// or https://.
not_found That song (or thing) is not there.
from_config That song comes from config/audio.lua. Change it there.
inventory_full The item does not fit.
no_framework No framework was found.
player_not_found No player with that ID.
is_admin You cannot do that to an admin.

Client exports

Call them from a client script:

Export What it does
openConsole() Opens the console (only for operators).
closeConsole() Closes it.
toggleDesk() Takes out or puts away the portable desk.
useDesk() Same, for inventory items.
openSetup() Opens the set-up editor (only for operators).
openAdmin() Opens the admin panel (only for admins).
getState() Returns { mounted, theme, nearby, track, consoleOpen, deskOut, quality }.
isNearby() true if the player is near the festival.
setQuality(name) 'low', 'medium' or 'high' for this player.
getQuality() Returns the player’s quality.
hasWristband(type?) true if the player has the wristband.

Events

The festival announces what happens. These are normal events, not network events: listen with AddEventHandler, on the same side (server or client).

Server events

Event Arguments
vault-festival:mounted mounted (true/false), by
vault-festival:originChanged origin (vector4), by
vault-festival:themeChanged themeId, by
vault-festival:islandChanged enabled, vegetation, by
vault-festival:trackStarted url, name, by
vault-festival:trackStopped by
vault-festival:effectFired effect, by
vault-festival:wristbandBought playerId, type ('general'/'vip'), price

by is the ID of the player who did it, or nil if it came from an export.

Client events

Event Arguments
vault-festival:mounted mounted
vault-festival:themeChanged themeId
vault-festival:trackStarted url, name
vault-festival:trackStopped (none)
vault-festival:effectFired effect
vault-festival:nearby isNearby (true when the player arrives, false when they leave)

Examples

Build the festival every Saturday at 21:00 (server)

CreateThread(function()
    while true do
        local now = os.date('*t')
        -- wday 7 = Saturday
        if now.wday == 7 and now.hour == 21 and now.min == 0 then
            if not exports['vault-festival']:isMounted() then
                exports['vault-festival']:mount()
            end
        end
        Wait(60000)
    end
end)

Give a VIP wristband from another script (server)

-- Called from YOUR server code (not from a client), e.g. when your contest picks a winner
AddEventHandler('mycontest:winner', function(playerId)
    local ok, err = exports['vault-festival']:giveWristband(playerId, 'vip')
    if not ok then print(('Wristband for %s failed: %s'):format(playerId, err)) end
end)

Never call these exports from a RegisterNetEvent handler without checking who sent it. Any player with a cheat menu can trigger net events and would get free wristbands.

Announce every new song in the chat (server)

AddEventHandler('vault-festival:trackStarted', function(url, name, by)
    TriggerClientEvent('chat:addMessage', -1, {
        args = { 'Festival', 'Now playing: ' .. (name or 'a new song') },
    })
end)

Open the console from an object with ox_target (client)

exports.ox_target:addModel(`prop_laptop_01a`, {
    {
        label = 'Festival lights',
        icon = 'fa-solid fa-sliders',
        onSelect = function()
            exports['vault-festival']:openConsole()
        end,
    },
})

Only operators can open it. Other players get a “not allowed” message.

Fire fireworks from a command (server)

RegisterCommand('finale', function(src)
    if src ~= 0 and not exports['vault-festival']:isAdmin(src) then return end
    exports['vault-festival']:fire('fireworks', true)
    exports['vault-festival']:fire('confetti', true)
end, false)

Do something when a player arrives (client)

AddEventHandler('vault-festival:nearby', function(isNearby)
    if isNearby then
        lib.notify({ title = 'Welcome to the festival!' })
    end
end)

Inventory item for the desk

For ox_inventory, the desk item uses the client export:

['festival_desk'] = {
    label = 'Portable lighting desk',
    weight = 800,
    stack = false,
    client = { export = 'vault-festival.useDesk' },
},

The ready-to-paste version is in install/items_ox.lua.

Back to the index