Sal's Kewl Holidays — owner's manual

What it does

Players with permission walk up to a building, string lights along the roofline, stand a tree in the plaza, hang a lantern by the door, and press play so the block dances to the music. Every piece is tagged with its holiday; the season calendar can turn each holiday's decorations on and off by date, so a city decorated once stays decorated every year.

• Point and click. /holiday opens a panel. Pick with the mouse; the ghost follows your crosshair; left click places, right click cancels.
• String lights on anything. Click points along a roofline, railing or doorway and the string runs between them, sagging like a real one (or not, per string). Six light types: mini, C9, rope, icicle, festoon globes, candle flicker. Seven patterns. Four channels.
• Inflatables. Seventy lawn blow-ups that ship as real game models: turkey, snowman, Santa, reindeer, jack-o-lantern, ghost, bunny, leprechaun, nine walkway arches and more across the holidays. One smooth skin each, lit from inside, casting light on the ground, solid enough to bump into.
• Wreaths. One per holiday, hung flat on the wall you aim at, with lights through them and a bow.
• Rope-light figures. Forty-seven of them: star, snowflake, tree, candy cane, bell, wreath, menorah, heart, shamrock, egg, pumpkin, bat, ring, snowman, reindeer, stocking, gingerbread man, angel, present, dreidel, Star of David, champagne glass, turkey, maple leaf, ghost, spider web, skull and more, hung flat on any wall and sized with the scroll wheel.
• See it before you place it. Every figure, inflatable and wreath has a picture in the panel; point at any row and it appears in the world at your crosshair. Props list what they are and how big.
• Props from the game's own catalog, verified against the object list, plus any streamed prop you add in Settings.
• Light shows. A track and a choreography drive the four channels of a group of lights, in sync for everyone nearby. 27 synthesized tracks ship (public-domain melodies and originals; nothing to license). Add your own.
• Sixteen sets: Christmas, Hanukkah, Kwanzaa, New Year's, Valentine's Day, St. Patrick's Day, Easter, Memorial Day, Independence Day, Labor Day, Halloween, Thanksgiving, and four dateless event sets: Party, Wedding, Birthday, Funeral / Memorial.
• Walkway arches and lit yard pieces. Candy cane, balloon, wedding and other arches that snap into a row along a path; a lit deer, stakes, orbs, lily stands, a candle vigil and more, drawn in game.
• Stationary objects only. Every decoration attaches to the map and to fixed objects. Nothing attaches to a vehicle or to anything that moves (the pier's Ferris wheel included): a string clicked onto one stays where it was clicked.
• No config.lua. Admins change every setting from the panel; changes are validated on the server and applied to everyone at once.

Installation

1. Extract the resource into your server's resources/ folder. The folder must be named sals_kewlholidays.
2. Add it to server.cfg after your framework (and after ox_lib if you use it):

   ensure sals_kewlholidays

3. Grant yourself admin (see section 3) if you are not already an admin of your framework.
4. Start the server. The console prints one line confirming what it found:

   [sals_kewlholidays] framework: qb  |  decorations: 0 loaded from data/decorations.json  |  season: all

5. Join, type /holiday, open Settings, and set the server up from there.

Requirements: none beyond a FiveM server. The framework (qb-core, qbx_core, es_extended or none) is detected at runtime. Notifications use ox_lib, qb-core, ESX or GTA's own feed. Any game build works; props from newer DLCs appear only on builds that have them (sv_enforceGameBuild).

Who may decorate, who is an admin

Every placement, move, removal and show is checked on the server. A player may decorate when any of these is true:

• Settings → Who may decorate → Everyone may decorate is on;
• they hold the decorator ACE (default holiday.decorate);
• their job is in the decorator jobs list (default admin, realestate, cityhall), on duty if "Jobs must be on duty" is on;
• they are an admin.

A player is an admin (Settings tab, remove anything, clear groups, change the season, start shows anywhere) when any of these is true:

• qb-core / qbx: the framework's admin or god permission; ESX: the admin or superadmin group;
• they are allowed FXServer's command ACE (the server-admin permission in the stock server.cfg);
• they hold the admin ACE (default holiday.admin).

To grant the ACE explicitly, in server.cfg (or the live console):

add_ace group.admin holiday.admin allow                        # if your admins are members of group.admin
add_ace identifier.license:<license> holiday.admin allow      # or one person, by identifier
add_ace group.admin holiday.decorate allow

Decorators who are not admins can only move and remove their own decorations (Settings → "Decorators edit only their own"). Caps per player and for the whole server, and the reach (how far from a spot a player may be while placing or editing), are in the same section.

The decorator panel

/holiday or numpad + opens it; the key, Esc or the × closes it. The key is a FiveM key binding: each player can change it under Settings > Key Bindings > FiveM, and the default comes from Commands.OpenKey (section 12). Recording a video? /holiday record hides the chat window and sends this resource's messages to F8 until /holiday record off. The left border takes the color of the holiday you are working on. The header shows the season mode and which holidays are in season now.

Point at a row and it appears in the world. While the panel is open, the prop, figure, inflatable or wreath under the mouse is drawn where your crosshair is (a prop turns slowly so you see every side; a figure hangs on the wall you are aiming at), so a decorator sees what "Snowman (scarf)" is before placing it.

While a tool is up, a tray sits at the bottom of the screen showing what you are placing and the keys. Press Tab to get the mouse cursor and click the tray's buttons (colors, pattern, channel, type, spacing, rotate, Finish, Cancel); Tab or Back to aiming returns to the crosshair.

Placing props

Pick a holiday and a prop, click Place. The panel closes and the ghost appears wherever your crosshair lands.

Lining things up

With Align to neighbors on (the default; a tray toggle, remembered per player), the ghost snaps to the nearest placed decoration of the same kind within 8 m: it takes that one's heading and height, and sits on the line through it. When two of the same kind already form a row, the next equal-spacing slot along the row is offered: aim near it and the ghost jumps to exactly the right spot, continuing the row's spacing and slope. A guide line is drawn from the neighbor to the ghost and the tray says what it is aligned to and at what spacing. Six jack-o-lanterns up a staircase: place two by hand, then click, click, click, click.

Props are created on each player's own client (not networked): they cost the server nothing, never count toward entity limits, cannot be pushed or picked up, and stream in and out by distance (large pieces from farther away). After placing, the panel comes back for the next one.

String lights

Pick colors, a light type, a pattern, a channel and spacing, then Start stringing. Aim at the first clip point (an eave corner, a railing post, the top of a door frame) and left click. Aim at the next and click again. The string previews live between points, with its real colors and pattern.

Outlining a sign or a roof

Clicking four corners of a sign from the street is slow and never quite square. The tray's Mode has three settings:

Each outline click adds its own stroke to the string, so the sign and the roof under it can go in one string and one show channel. Backspace still removes the last point, so a wrong outline is five presses. If the tool cannot find the edges (a curved or broken-up surface) it says so; click the corners instead. The string sits 5 cm inside the edge and follows it exactly when Sag is off.

Light types

Patterns

Steady, Twinkle (random winks, identical for every player), Chase (every third bulb walks along the string), Alternate (every other bulb swaps), Fade (the whole string breathes), Wave (a brightness wave travels along it), Flicker (flame). Chase, alternate, fade and wave take their speed from the track's tempo during a show.

Sag

By default a string droops between the points you click, like a real one hung from clips; the droop grows with the span and is capped. Turn Sag between points off (Lights tab, or the tray) for a string that follows the outline exactly. Figures never sag.

Rope-light figures

Pick a figure, colors, a light type (rope is the default) and a channel, click Hang on a wall, then aim at a wall. The figure previews flat on it, sized with the scroll wheel (Shift for bigger steps); ← → tilt it; E pins it; left click hangs it; right click ends the run. On a floor or ceiling the figure lies flat. Repeat and Align to neighbors work exactly as for props: hang two snowflakes, and the third snaps to the same height and spacing along the wall.

Figures ship per holiday. Christmas: star, snowflake, tree, candy cane, bell, wreath, snowman, reindeer, Santa hat, stocking, gingerbread man, angel, present, bow, candle. Hanukkah: snowflake, menorah, dreidel, Star of David, present, candle. New Year's: star, snowflake, bell, ring, champagne glass, midnight clock, firework burst, balloon. Valentine's: heart, heart and arrow, rose, tulip, bow, champagne glass. St. Patrick's: shamrock, rainbow and pot of gold, leprechaun hat. Easter: egg, bunny, chick, tulip, angel. Independence Day: star, US flag, firework burst. Halloween: pumpkin, bat, ghost, spider web, skull, witch hat, black cat, crescent moon. Thanksgiving: ring, turkey, maple leaf, pilgrim hat, acorn, candle. Party: star, heart, ring, present, bow, champagne glass, firework burst, balloon, music note, crescent moon. Each is pictured in the panel. A figure is stored as an ordinary string of lights, so shows, channels and editing all apply. Add your own in shared/figures.lua: strokes in a unit square.

Inflatables and wreaths

The game has no lawn inflatables and no wreaths. Inflatables ship as real game models (stream/, seventy of them): each is built from the lit shapes in shared/shapes.lua (a turkey is a brown body, a fanned tail, a head and a wattle, each an ellipsoid) and fused into one smooth vinyl skin, with an emissive shader so it glows at night and a light inside that falls on the ground around it. They are ordinary props to the game: they cast shadows, take its lighting, and you bump into them. The models load with the resource on every game build; no other resource is needed. Wreaths, arches' thin lit variant and the yard pieces are still drawn in game from the same shapes, with nothing spawned.

Inflatables (the Inflatables tab): snowman, Santa, reindeer, penguin, polar bear, candy cane, Christmas tree and gingerbread man; menorah and dreidel; gold star, champagne bottle, birthday cake and disco ball; heart and a bear with a heart; shamrock and leprechaun; bunny, Easter egg and chick; Uncle Sam hat and firecracker; jack-o-lantern, ghost, black cat, spider, bat and witch; turkey, harvest pumpkin, scarecrow and acorn. Pick one, click Place, aim: it is placed like a prop (section 5; scroll rotates, Repeat and Align work), and Page Up / Page Down or the tray's +/− set its height (0.4 to 8 m; each has a sensible default).

Each comes in one size, shown on its card (1.4 to 3 m); a model cannot be resized in game, so Page Up / Page Down do nothing on these. Older drawn inflatables still inflate. One placed with a version before 0.6.0 is still drawn from its shape: it rises out of a heap on the ground over a few seconds when placed, sinks back when removed, and sways a little in the wind while up. Aim at one with the Edit tool (section 11) and the tray offers Deflate or Inflate: a deflated one stays on the lawn as a heap until it is inflated again. With Deflate during the day on (Settings → Inflatables and wreaths), every inflatable lies deflated between the day hours and stands up again at dusk, the way a real yard does.

Wreaths sit at the top of the Props tab, one per holiday: evergreen with warm white lights and a red bow for Christmas, blue and silver for Hanukkah, roses for Valentine's, autumn leaves for Thanksgiving, black branches with orange lights for Halloween, and so on. They hang flat on the wall you aim at and Page Up / Page Down set the diameter (0.3 to 4 m).

Arches (candy cane, top hat, Happy Holidays, rainbow, fireworks, Pan-African, balloon, wedding, and a thin lit arch) are inflatables wide enough to walk through at their default height. Place one over the walk, facing along it. With Align on, an arch's row runs along the path it spans rather than across its face, so the next one snaps into line at the same spacing: a sidewalk takes three clicks.

Lit yard pieces sit below the inflatables in the same tab: a lit deer, a Star of Bethlehem on a pole, lit ornaments and orbs, sunflowers, a snowflake stake, a soldier silhouette, a lit cross, lily stands, a candle vigil, a draped casket. They stand where placed, drawn bright and matte, and do not inflate. Wall pieces sit beside the wreaths at the top of the Props tab: window candles, patriotic and mourning bunting, the Kwanzaa banner.

Each part is a small triangle mesh drawn with plain polygons, back faces culled, parts painted far to near, shaded from its own color so the roundness reads. Both are drawn under a per-frame triangle budget like the lights (nearest first: fine mesh up close, coarse mesh farther, one blob of the main color beyond the detail distance), scaled by each player's quality setting. The light inside is cast only within 60 m. Add your own in shared/shapes.lua: a list of ellipsoids in a unit-tall box, and the panel draws its picture from the same list.

Light shows and music

A show is a track plus a choreography, run against every string in one group. The choreography is a list of steps; each lasts some beats of the track and sets each of the four channels to a pattern. It loops until the track ends. Everyone within hearing distance of the group's lights hears the track and sees the same thing; late arrivals join in sync.

Open Shows, confirm your location, pick a choreography, press Play on a track. Stop the show ends it early. A show for a holiday that is out of season is refused unless you are an admin.

Shipped choreographies

Put the roofline on channel 1, the windows on 2, the tree on 3 and the door on 4, and Dance and Build play them against each other.

Tracks

27 ship, synthesized from note data: Jingle Bells, Deck the Halls, We Wish You a Merry Christmas, Carol of the Bells, Up on the Housetop, Joy to the World, O Christmas Tree, Silent Night, Ma'oz Tzur, The Dreidel Song, Hava Nagila, Auld Lang Syne, Midnight Chimes, Valentine Waltz, The Irish Washerwoman, Shamrock Reel, Morning Mood, Easter Bells, The Star-Spangled Banner, Yankee Doodle, America the Beautiful, In the Hall of the Mountain King, Graveyard Waltz, Haunted Ambience, Over the River and Through the Wood, Harvest Home, Block Party. The melodies are public domain or original; the arrangements are ours. Nothing needs clearing.

Your own music: drop an .ogg in the resource's audio/ folder, restart the resource once so the file is served, then register it in Settings → Custom tracks (name, label, file, length in seconds, tempo, holiday). Volume is full within the near distance and silent past the far one; players can mute shows for themselves.

The season calendar

Every decoration belongs to a holiday. The season mode (Settings → Season calendar, or /holiday season) decides which holidays' decorations players see:

• all (the shipped default): everything, all year.
• auto: each holiday only inside its date window. Easter is computed per year (two weeks either side of Easter Sunday). The calendar is re-checked every ten minutes, so decorations switch at midnight without a restart.
• none: nothing (decorations are kept, not shown).
• a holiday name: only that holiday, whatever the date.

Windows and on/off per holiday are in Settings → Holiday dates (MM-DD). Overlaps (Christmas, Hanukkah, New Year's) are deliberate: leave the roofline up and swap the palette to gold.

Winter touches (off by default): tire trails and footprints in snow while Christmas is in season. Weather is left alone unless "Force snow weather" is on, because your weather resource owns it.

Editing, locations, layouts and channels

Aim and click. Edit tab → Aim and click a decoration (or /holiday edit). Aim at anything placed: it lights up with its name, holiday, group, owner and distance in the tray. A prop is found by the crosshair hitting it; a string is found by the crosshair ray passing close to its wire, so a string on a roofline is as clickable as a tree; an inflatable or wreath by the ray passing through its box. An inflatable's tray adds Deflate / Inflate. Left click opens its actions: Remove, Move (a prop goes back into the placer, a figure is re-hung) or Edit the string (re-runs the point tool with the points already in it), and Move to group (pick a group chip or type a new name). A string made of several strands (outlines, door frames) highlights the strand you are aiming at in orange and offers Remove this strand beside Remove; pressing Delete while aiming does the same without opening the tray. Back to aiming keeps the tool up for the next one; right click or Leave the tool ends it. Someone else's decoration shows its details but no buttons unless you are an admin.

Edit list: everything within reach, nearest first, with a group dropdown, Move and Remove on each you may edit. Undo my last placement removes the last thing you placed this session. Admins can remove anything; decorators only their own.

Locations: every decoration belongs to a location, your current one when you placed it; default main. Name locations after the place: firehouse, hospital, 247 sandy (spaces are allowed, up to 32 characters). You never have to remember a name: the Shows, Edit, Locations and Settings tabs list every location that exists with its decoration count and how far away it is; click one to make it yours or type a new name and press Use. The Edit tab's list adds Clear for admins (click twice). /holiday locations prints the list; /holiday location 247 sandy sets yours. A show runs against one location, and so does an admin clear, which is the reason to keep a location to one building. (The setting path and the save file still call this field group.)

A location holds a set per holiday. Every decoration keeps the holiday it was placed under, so the firehouse can hold a Christmas set and a Halloween set, and the calendar shows whichever is in season. The Locations tab shows one chip per holiday at each location with its count and a dot when that holiday is in season; an admin clicks a chip twice to clear just that set (/holiday clear firehouse halloween does the same, as does holidayadmin clear firehouse halloween from the console), leaving the other holidays in place. Below the list, admins have Clear every decoration on the server: click Clear, it arms with the total and disarms itself after a few seconds, click again and every location and every holiday comes down at once (/holiday clear all and holidayadmin clear all do the same). Saved layouts are kept, and the server writes a copy of the decorations first, data/decorations.json.before-clear-<time>, so a wrong click is undone by renaming that copy over decorations.json and restarting the resource.

Travel: the Locations tab lists every decorated location with a Travel button: a short fade and you are standing at its nearest decoration, vehicle included. Decorators and admins only.

Layouts, for next year: Save my location as a layout copies everything at your current location under a name, with a note for your future self ("Firehouse 2026: roofline on channel 1, tree by the bay door; check the new awning"). Tick Only this holiday to save one holiday's pieces out of a mixed location. After the holiday, clear the location. Next year, open the Locations tab: each layout shows its count, holidays, who saved it and when, and whether it has been checked this year. Travel there (which stamps it checked), Load (add) puts the saved decorations back beside whatever is there, Load (replace) clears the location first (click twice; a decorator can only replace a location that holds nothing of anyone else's). Then edit with the normal tools (an MLO update may have moved a wall) and Save over. Rename / note and Delete are yours on layouts you saved; admins have them on all. Next location walks the list one Travel at a time. /holiday go <layout> travels from chat. Layouts are kept in data/presets.json, backed up on every write. A loaded decoration is placed as yours and counts against your cap; a prop the catalog no longer has, or a holiday turned off, is skipped and counted in the message.

Channel: every string has a channel 1–4 (My settings sets the default for new strings). A show drives the four channels separately.

Viewing time: My settings → Viewing time (or /holiday time night) sets your own clock so you can see the lights after dark while the server is at noon. Nobody else is affected; /holiday time reset returns to server time.

Settings reference

Settings → Server settings (admins). Every change is validated on the server, saved to data/settings.json, and applied to every player immediately. Reset everything to defaults is at the bottom.

Who may decorate

Season calendar

Props

Lights

Inflatables and wreaths

Music

Updates

The Updates row at the top of Server settings shows the running and latest versions with Check now and Apply update; a newer version lists its changelog there. /holidayadmin update check and /holidayadmin update apply do the same from chat or the server console. A resource cannot create folders or delete files: a release that adds a new folder reports the files it could not place (create the folder, apply again), and files a release removed simply stop being loaded.

Other

Commands

Everything in the panel is a click; these exist for admins who prefer typing, for key binds, and for the console.

Performance

• Props are local, non-networked objects streamed by distance. The server never owns an entity; the entity budget is never touched.
• Lights are rendered under a hard per-frame budget: at most Bulbs per frame bulbs and Cast lights per frame real light sources, nearest strings first, the rest skipped that frame. Bulb positions are computed once per string, not per frame. A separate emergency ceiling on script triangles per frame exists so no combination of strings and previews can overflow the engine's draw buffer.
• Players tune their own cost with the quality setting (low scales the budgets to 35%, medium 70%, high 100%, ultra 160%). A player on a weak PC turns it down without the owner changing anything.
• The server does no per-frame work at all. It validates requests, keeps the registry, times shows, and re-checks the calendar every ten minutes.

Files, saving and backups

Two files, both inside the resource's data/ folder:

• decorations.json — every decoration. Written a few seconds after a change, and on a graceful stop.
• settings.json — what admins changed in game. Written on every change.

Saving follows the same rules as Sal's Kewl Signage: the server never saves before it has loaded the file in this process; it backs up the previous contents to .bak before every write; it reads the file back to verify the write; it keeps the file as it stood at each of the last three boots (.1, .2, .3); and it refuses a save that would shrink the file by more than the removals it was told about (the refused contents are kept beside it as .refused-<time>). If the data/ folder is missing it saves beside fxmanifest.lua instead and says so in the console. /holiday status reports saving health.

Keep data/ when you upgrade. The release never ships files under those names.

Decorating tips

Troubleshooting

For developers

-- Server exports
exports['sals_kewlholidays']:GetActiveHolidays()           --> { christmas = true, ... }
exports['sals_kewlholidays']:GetSeasonMode()               --> 'all'
exports['sals_kewlholidays']:StartShow(group, track, show) --> boolean
exports['sals_kewlholidays']:StopShow(group)               --> boolean
exports['sals_kewlholidays']:IsShowRunning(group)          --> boolean
exports['sals_kewlholidays']:GetDecorations()              --> list of records

Records: { id, kind = 'prop' | 'lights', holiday, group, by, byName, updated, model, coords, heading } for props; { ..., points, breaks, figure, palette, pattern, spacing, channel, size, sag, length } for lights.

The prop catalog and palettes are in shared/holidays.lua, figure templates in shared/figures.lua, inflatable and wreath templates in shared/shapes.lua, defaults and the settings schema in shared/defaults.lua, all readable. tools/build-audio.py rebuilds every track from note data (numpy and ffmpeg).