> For the complete documentation index, see [llms.txt](https://sl-scritps.gitbook.io/sl-scripts-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sl-scritps.gitbook.io/sl-scripts-documentation/products/sl-vintage-jukebox.md). # SL Vintage Jukebox ## SL Vintage Jukebox **Code:** JBX-19\ **Resource:** `sl_vintage_jukebox`\ **Version:** v1.1.5\ **Category:** Social RP / Music / World Interaction\ **Status:** Stable **Structured tools for serious roleplay servers.** *** ### Overview SL Vintage Jukebox is an immersive jukebox system for FiveM roleplay servers. It allows servers to add interactive jukeboxes to bars, diners, clubs, restaurants, lounges, event areas or custom interiors. Players can interact with a jukebox in-world, play music, view what is currently playing and create social ambience around a physical object. The resource is designed to feel like a real jukebox inside the world, not just a music command or an out-of-character menu. *** ### What is this script for? SL Vintage Jukebox gives servers a simple and immersive way to create music-based social roleplay. It is useful for: * Bars * Diners * Clubs * Lounges * Restaurants * Event spaces * Social meeting points * Retro / vintage interiors * Player-owned businesses * Staff-created RP scenes The main goal is to make music feel connected to a physical jukebox that players can see, approach and use. *** ### Roleplay Experience SL Vintage Jukebox is designed around a clear IC idea: ```txt The player walks up to a jukebox. The player interacts with it. The jukebox starts playing music in the area. Other players nearby can use that music as part of the scene. ``` This makes the system useful for ambient roleplay, business roleplay and social gatherings. Instead of using an OOC music command, the server can place a jukebox inside the world and let players treat it as part of the location. *** ### Player IC Usage For players, SL Vintage Jukebox should feel like using a real jukebox inside the world. The player does not need to understand the technical setup. The normal roleplay flow is: ```txt Walk to the jukebox → interact → choose/control music → enjoy the scene ``` Common IC actions: * Put music on in a diner * Start background music in a bar * Change the atmosphere of a social scene * Use music during a date, meeting or hangout * Create ambience during a business opening * Gather players around a shared object * React to what is currently playing * Use the jukebox as part of a casual RP moment Example IC lines: ```txt “I’ll put something on the jukebox.” “This place needs some music.” “Let me change the song.” “The jukebox is working again.” “Put something old-school on.” ``` The jukebox works best when players treat it as part of the location, not as an out-of-character music menu. *** ### Player / IC Flow #### 1. The player finds a jukebox The jukebox can exist as: * A map prop already inside an MLO * A placed jukebox created by an admin/owner * A configured jukebox location * A business or event object The player approaches the jukebox in the world. *** #### 2. The player interacts with it Depending on server configuration, the player may interact through: ```txt target interaction draw text / fallback interaction command fallback ``` In roleplay terms, the character is walking up to the jukebox and selecting music. Expected result: ```txt The jukebox menu opens. ``` *** #### 3. The player selects or controls music The jukebox menu can be used to control the music experience depending on configuration. Common actions may include: * Play music * Stop music * View currently playing track * Adjust volume if allowed * See playback status * Use available jukebox options The exact options depend on how the server configured the resource. *** #### 4. Nearby players experience the scene The jukebox is meant to support shared spaces. Examples: ```txt A diner feels alive with background music. A bar owner starts a song during an event. Players gather around a vintage jukebox. A staff member creates ambience for a roleplay scene. ``` This makes the jukebox more than a utility. It becomes part of the environment. *** ### Admin / Owner IC Usage For admins, owners, staff or business managers, the jukebox can be used as an in-world tool to prepare social spaces. The admin flow is not only technical. It can also support IC worldbuilding. Common admin/owner IC uses: * Place a jukebox inside a diner, bar, club or lounge * Prepare ambience for a business opening * Add a music point to an event area * Create a retro/vintage corner inside an interior * Give a player-owned business a usable music object * Test whether players can interact with the jukebox naturally * Remove or relocate a jukebox if the layout changes * Build social spaces that feel more alive Example IC/admin flow: ```txt Choose location → place jukebox → test interaction → set volume/range → open the space for players ``` Example admin RP use: ```txt A staff member prepares a 50s diner event. They place a vintage jukebox near the counter. They test the interaction and music range. Players enter the diner and use the jukebox as part of the scene. ``` For business roleplay, the jukebox can be treated as part of the venue setup: ```txt The owner installs a jukebox. Employees use it during opening hours. Customers interact with it while hanging out. The music helps the business feel alive. ``` Admins should still manage placement, permissions and persistence from the technical side, but the goal is to make the object feel natural inside the RP world. *** ### Admin / Owner Technical Flow Owners/admins can place and manage jukeboxes when the map or MLO does not already include one. This is useful when: * The interior has no real jukebox prop * The server wants a jukebox in a custom location * A business needs its own music point * A staff member is preparing an event area * The existing visible prop cannot be detected by the resource Common admin actions may include: * Open admin menu * Place a new jukebox * Choose jukebox model * Register a jukebox location * Remove a jukebox * Configure volume/range behavior * Test interaction * Confirm the jukebox persists after restart Recommended admin checks: ```txt 1. Place the jukebox. 2. Restart the resource. 3. Confirm the jukebox still exists if persistence is enabled. 4. Interact with the jukebox. 5. Test music playback. 6. Test range and volume. 7. Test delete/remove flow. ``` *** ### Example IC Scenarios #### Diner roleplay A group of players enters a retro diner and one player walks to the jukebox. ```txt “I’ll put something on while we wait for the food.” ``` #### Bar event A bartender or event host uses the jukebox to create atmosphere. ```txt “Music is on. The place is open.” ``` #### Social hangout Players gather around a social location and use the jukebox as part of the scene. ```txt “This song fits the moment.” ``` #### Staff-created scene Staff places a jukebox in an event area to create ambience. ```txt “The event area now has music from the jukebox.” ``` #### Player-owned business A business owner places or requests a jukebox for their venue. ```txt “We installed a jukebox for customers.” ``` *** ### What this resource is not SL Vintage Jukebox is not intended to be a full DJ booth, radio station or complex music production system. It is focused on: ```txt physical jukebox interaction social music roleplay placement area ambience simple music control vintage-style object usage ``` For best roleplay results, servers should use it as an in-world music object for social spaces. *** ### Main Features * Interactive jukebox system * Physical world-based interaction * Vintage jukebox style * Admin placement support * Map prop detection when available * Fallback placement when no jukebox exists in the MLO * Now Playing display * Volume / range visibility when configured * Persistent jukeboxes when database mode is enabled * Target interaction support * Command fallback support * Admin/owner management flow * Configurable models * Configurable interaction distance * ES/EN locale support * Clean SL Scripts style * Suitable for bars, diners, clubs and social RP spaces *** ### Dependencies #### Required ```txt FiveM server ``` #### Recommended / Optional ```txt ox_lib ox_target qb-target oxmysql QBCore Qbox ESX Standalone mode ``` The exact dependency setup depends on how the resource is configured. If persistence is enabled, database support may be required. If target interaction is enabled, make sure your target resource starts before `sl_vintage_jukebox`. *** ### Installation Notes 1. Place the resource folder inside your server resources folder. Example: ```txt resources/[sl_scripts]/sl_vintage_jukebox ``` 2. Make sure the folder name is: ```txt sl_vintage_jukebox ``` 3. Configure: ```txt config.lua custom.lua locales/ ``` 4. If the resource includes SQL and persistence is enabled, import: ```txt sql/install.sql ``` or use automatic migrations if supported by your build. 5. Add the resource to your `server.cfg`. Example: ```cfg ensure oxmysql ensure ox_lib ensure ox_target ensure sl_vintage_jukebox ``` If you are not using `ox_target`, configure your preferred interaction mode in `config.lua`. *** ### Placement Flow SL Vintage Jukebox can work with existing map props or placed jukeboxes. #### Existing map jukebox If the MLO already includes a supported jukebox prop, the resource can detect and register it depending on configuration. This is useful for interiors that already have a jukebox model. *** #### Placed jukebox If the MLO does not include a real jukebox prop, an admin can place one manually. Basic admin flow: ```txt Open admin menu Choose jukebox model Start placement Move/rotate the preview Confirm placement Jukebox becomes usable ``` Recommended placement controls: ```txt Scroll = rotate ENTER = confirm BACKSPACE / ESC = cancel ``` The exact controls may depend on configuration. *** ### Map Prop Fallback Some interiors visually look like they should have a jukebox, but the actual map may not include a usable jukebox prop. In that case, there is nothing for the resource to auto-detect. If this happens, use the admin placement option: ```txt Place new jukebox ``` This lets the admin create a real interactive jukebox where the MLO does not provide one. *** ### How to Use #### Basic Player Flow 1. The player approaches a jukebox. 2. The player interacts with the jukebox. 3. The jukebox menu opens. 4. The player selects or controls music depending on permissions/configuration. 5. The jukebox plays music for the configured area. 6. Players nearby can use the scene for roleplay. #### IC Summary ```txt Find jukebox → interact → choose music → music plays in the area ``` #### OOC / Technical Summary ```txt Approach registered jukebox → target/fallback interaction → NUI/menu opens → server validates action → playback state updates ``` *** ### Commands Command names may depend on configuration. Common command examples: ```txt /jukebox ``` Possible admin command examples: ```txt /jukeboxadmin /sl_jukebox /sl_jukebox_admin ``` Check `config.lua` for the exact command names used by your installed version. Commands are useful as fallback access, testing tools or admin shortcuts. *** ### Permissions Permission setup depends on server configuration. Common permission levels may include: ```txt view use manage admin owner ``` Recommended access logic: ```txt Players = use nearby jukeboxes Business staff = use/manage assigned jukeboxes if configured Admins = place, remove and manage jukeboxes Owners = full access ``` Permissions may use: * Ace permissions * Framework groups * Jobs * Job grades * Config admin list * Custom permission bridge Check `config.lua` and `custom.lua` for your server setup. *** ### Configuration Open: ```txt config.lua ``` Common settings may include: ```txt Product information Locale Debug mode Startup logs Interaction mode Target settings Command settings Jukebox models Map prop detection Placement options Volume settings Range settings Persistence settings Admin permissions Framework bridge Notify bridge Database settings ``` Recommended for production: ```lua Config.Debug = false ``` Use debug mode only while testing or troubleshooting. *** ### Custom Integrations Open: ```txt custom.lua ``` Use this file for server-specific functions such as: * Custom notifications * Custom permission checks * Custom framework integration * Custom logging * Custom business/job access * Custom admin checks If your server uses standard systems, you may not need many changes here. *** ### Startup Logs When the resource starts correctly, you may see logs similar to: ```txt [sl_vintage_jukebox][INFO] Server ready: SL Vintage Jukebox v1.1.5 [sl_vintage_jukebox][INFO] Client ready: SL Vintage Jukebox v1.1.5 | Use /jukebox ``` If startup logs are disabled, check `config.lua`. *** ### Troubleshooting #### The jukebox does not appear Check: ```txt - The jukebox prop exists in the MLO. - The configured model is supported. - Map prop detection is enabled if using existing props. - You are close enough to the jukebox. - Target interaction is enabled and started. ``` If the MLO does not contain a real jukebox prop, use admin placement. *** #### I see a jukebox visually, but it is not detected Some MLOs may include decorative objects that are not the expected jukebox model or not detectable as a usable prop. Fix: ```txt Use admin placement and place a new interactive jukebox. ``` *** #### Target interaction does not appear Check: ```txt - ox_target or qb-target is started. - Target mode is enabled in config.lua. - The target resource starts before sl_vintage_jukebox. - You are close enough to the jukebox. - Your job/permission allows access. - The jukebox was registered correctly. ``` Try restarting the resource after the target system is already running. *** #### Admin placement does not work Check: ```txt - You have admin/owner permission. - Admin placement is enabled in config.lua. - The selected model exists. - You are not inside a blocked placement area. - F8 console has no errors. - Server console has no errors. ``` *** #### Jukebox disappears after restart Check: ```txt - Persistence is enabled. - Database is configured correctly. - oxmysql starts before sl_vintage_jukebox. - SQL tables exist. - Placement was confirmed correctly. ``` If persistence is disabled, placed jukeboxes may not remain after restart. *** #### Music does not play Check: ```txt - The music source/link is valid if your configuration uses external URLs. - The playback action is allowed by permissions. - Volume is not set to 0. - Range is configured correctly. - Client F8 console has no audio/NUI errors. - Server console has no validation errors. ``` *** #### Volume or range feels wrong Check: ```txt - Volume settings in config.lua. - Range settings in config.lua. - Distance from jukebox. - Any server-side audio limitations. - Whether the jukebox is inside an interior/MLO with unusual audio behavior. ``` *** #### Delete/remove does not work Check: ```txt - You have admin/owner permission. - Delete confirmation was accepted. - Database update succeeded if persistence is enabled. - The jukebox entity exists and is registered. ``` *** ### Version Notes #### v1.1.5 * Added/improved fallback placement flow for maps or MLOs without a real jukebox prop. * Admin menu includes guidance for cases where no jukebox appears. * Model selection for vintage placement is supported. * Existing map prop detection remains supported when the prop exists. * Focused on making the system easier to use across different interiors. #### v1.0.x * Stable public release line. * Persistent jukebox behavior supported. * Basic interaction, volume/range visibility and Now Playing behavior supported. * Delete confirmation and ES/EN support included. *** ### Support When asking for support, include: ```txt Product: SL Vintage Jukebox Resource name: sl_vintage_jukebox Version: Framework: Target system: Database: Issue: Steps to reproduce: Server console error: Client F8 error: Screenshot/video: ``` Example: ```txt Product: SL Vintage Jukebox Resource name: sl_vintage_jukebox Version: v1.1.5 Framework: Qbox Target system: ox_target Database: oxmysql Issue: Jukebox does not appear in my diner MLO Steps to reproduce: Go to diner location and try to interact with visible jukebox Server console error: none Client F8 error: none Screenshot/video: attached ``` *** ### Final Notes SL Vintage Jukebox works best when treated as a physical RP object. For best results, place jukeboxes in social spaces where players naturally gather, such as diners, bars, clubs, lounges, restaurants and event interiors. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://sl-scritps.gitbook.io/sl-scripts-documentation/products/sl-vintage-jukebox.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.