For developers
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
RegisterNetEventhandler 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.