Skip to main content

HSC Loading Screen — Complete Documentation

Product: HSC Loading Screen
Publisher: Hotspot Creations
Documented version: 1.0.1 — Online Music Support
Platform: FiveM
Framework: Standalone (compatible with QBCore, Qbox, ESX and others)

This guide was written from the supplied hsc_loadingscreen_v1.0.1_online_music.zip resource. It distinguishes built-in functionality from examples or changes that require custom development. Code samples showing partial objects are not complete replacements for web/config.js.

Contents​

  1. Overview and features
  2. Quick start
  3. Installation and compatibility
  4. File structure and fxmanifest
  5. Editing config.js safely
  6. Server branding and text
  7. Adding a custom logo
  8. Theme colors and effects
  9. Image slideshow backgrounds
  10. Video backgrounds and fallback
  11. Real FiveM progress and messages
  12. Community tips
  13. Information panels overview
  14. Welcome panel and stats
  15. Features and rules panels
  16. Team panel
  17. Social links and store URLs
  18. Music player basics and controls
  19. Adding local music files
  20. Playing music from a URL
  21. Internet radio and streaming endpoints
  22. Fallback tracks, timeouts and errors
  23. Music keyboard shortcuts and autoplay
  24. Visual layout and advanced CSS
  25. Browser preview and FiveM testing
  26. Troubleshooting common issues
  27. Updating from v1.0.0 to v1.0.1
  28. Developer reference and limitations
  29. Performance and production checklist
  30. FAQ
  31. Support and release information

1. Overview and features​

HSC Loading Screen is a standalone, configurable FiveM loading screen created by Hotspot Creations. The interface runs in FiveM's embedded browser (NUI/CEF), reads its settings from web/config.js, and does not require QBCore, Qbox, ESX, ox_lib, Node.js, a database, or a frontend build process.

Included in v1.0.1​

  • Live FiveM loading progress displayed as a percentage and progress bar.
  • Server logo, server identity, status, welcome text, and description.
  • Rotating image backgrounds, or an optional muted looping MP4 background with image fallback.
  • Theme colors, dark overlay, grid, grain, and animated ambient effects.
  • Rotating connection tips and progress-dependent loading messages.
  • Clickable Welcome, Features, Rules, and Team information panels, with optional automatic rotation.
  • Up to four visible social links.
  • A music player supporting packaged audio and direct online audio URLs or compatible streams.
  • Play/pause, previous/next, mute, volume slider, keyboard controls, track status, and fallback tracks.
  • Responsive layout, reduced-motion support, and simulated progress in local browser preview.

What is not included​

  • No YouTube, Spotify, SoundCloud, or Apple Music webpage player or URL-to-audio extractor.
  • No automatically updated staff roster, live server status, dynamic player count, or server-side data bridge.
  • No database-backed editor or in-game configuration UI.
  • No built-in music downloader or content hosting.
  • No manual loadscreen shutdown integration in the shipped manifest.

Documented release: hsc_loadingscreen_v1.0.1_online_music.zip. Steps and setting names in this guide were checked against that package. Code identified as an example must be customized before use.

2. Quick start​

To get the loading screen working with minimal customization:

  1. Extract the downloaded package. Keep the final resource folder named hsc_loadingscreen.

  2. Move that folder under your server's resources directory (for example, resources/[standalone]/hsc_loadingscreen).

  3. Add the following to server.cfg:

    ensure hsc_loadingscreen

  4. Open hsc_loadingscreen/web/config.js in VS Code or another plain-text editor.

  5. Change server.name, server.shortName, server.tagline, and server.description.

  6. Change the URLs under socials; the provided values belong to the demo.

  7. Configure your own music files or URLs under music.tracks, or set music.enabled: false if you do not want music.

  8. Start/restart the server, join from FiveM, and verify the appearance and loading progress.

Optional: Hide FiveM's default loading spinner by adding:

setr sv_showBusySpinnerOnLoadingScreen false

You can make most changes without touching web/app.js or web/index.html. A browser preview is available by opening web/index.html locally, but always verify the final result in FiveM.

3. Installation and compatibility​

Requirements​

  • Working FiveM server with access to server.cfg and the resource directory.
  • FiveM client for in-game tests.
  • A text editor for web/config.js.
  • A network connection only if your setup loads external resources such as online audio.

Installation layout​

server-data/
├── server.cfg
└── resources/
    └── [standalone]/
        └── hsc_loadingscreen/
            ├── fxmanifest.lua
            ├── README.md
            ├── CUSTOMIZATION.md
            ├── CHANGELOG.md
            └── web/
                ├── index.html
                ├── config.js
                ├── app.js
                ├── style.css
                ├── assets/
                └── media/

fxmanifest.lua must be directly inside hsc_loadingscreen, not in an extra nested folder. Keep only one intended loadscreen resource active; simultaneous loadscreen declarations can conflict.

Start it​

ensure hsc_loadingscreen

For a server already running, execute refresh and ensure hsc_loadingscreen in its console. A full restart and a fresh client connection are recommended when checking the loading experience.

Frameworks​

The resource is framework-independent. It can run on standalone, QBCore, Qbox, ESX, and other FiveM configurations. Framework job, staff, and player data are not automatically read by this product.

File/download considerations​

  • Packaged media is served to joining players; large MP4/music files increase resource download weight.
  • External audio requires the client to reach the external host and to have a playable audio source.
  • Keep directory/file capitalization consistent, especially on Linux-hosted servers.

4. File structure and fxmanifest​

Important files​

FilePurposeNormal customer edit?
fxmanifest.luaRegisters the loading page and packaged asset paths.Only when adding new asset types/paths.
web/config.jsServer details, theme, media, panels, music, socials.Yes.
web/index.htmlUI markup and script/style references.Advanced layout edits only.
web/style.cssResponsive layout, fonts, spacing, player and panels.Optional advanced design.
web/app.jsProgress, slideshow, panels, audio player, NUI behavior.Not normally.
web/assets/*.svgBundled backgrounds and placeholder logo.Replace or add art as needed.
web/media/*Locally hosted MP3/OGG/WAV/MP4 files.Add your own licensed media.
README.md, CUSTOMIZATION.md, CHANGELOG.mdOriginal product instructions.Reference materials.

The supplied fxmanifest.lua includes:

fx_version 'cerulean'
game 'gta5'

loadscreen 'web/index.html'
loadscreen_cursor 'yes'

files {
    'web/index.html',
    'web/style.css',
    'web/config.js',
    'web/app.js',
    'web/assets/*.svg',
    'web/media/*'
}

The manifest also sets resource metadata (name, author, description, version) and has escrow_ignore entries for editable UI/media paths.

Important asset rule: The current web/assets/*.svg rule packages SVG images only. If your new logo is web/assets/my-logo.png, add 'web/assets/*.png' (or the exact file path) to the files list. Likewise, add a WebP glob if you use WebP images in web/assets. Files under web/media/* are covered by that wildcard.

files {
    'web/index.html',
    'web/style.css',
    'web/config.js',
    'web/app.js',
    'web/assets/*.svg',
    'web/assets/*.png',
    'web/assets/*.webp',
    'web/media/*'
}

This is an example manifest adjustment, not a separate file you must install.

5. Editing config.js safely​

The single source of standard settings is:

hsc_loadingscreen/web/config.js

It exports a JavaScript object through window.HSC_LOADING_CONFIG. Edit property values while keeping property names and nesting intact.

window.HSC_LOADING_CONFIG = {
    server: {
        name: 'My Roleplay Server',
        shortName: 'MYRP',
        tagline: 'Your next chapter begins here.',
        description: 'Explore our city and create your own story.',
        logo: 'assets/logo-placeholder.svg',
        statusText: 'Connecting to the city'
    },
    // More sections exist below in the actual file.
};

The snippet above is partial; do not replace the entire shipped file with it.

JavaScript rules to remember​

  • Strings use quotes: 'My Server'.
  • Booleans use unquoted true or false.
  • Arrays use [ ... ] for lists of backgrounds, tips, rules, or tracks.
  • Objects use { ... } for grouped settings and individual records.
  • Separate adjacent properties/array entries with commas. Trailing commas are permitted in modern JavaScript.
  • Do not delete window.HSC_LOADING_CONFIG = or change names such as music.tracks.
  • Relative paths in settings are resolved against the web/ folder: media/song.mp3 means web/media/song.mp3.
  • https://... URLs should be complete absolute links.

Good workflow​

  1. Make a backup of the current web/config.js.
  2. Change one section at a time.
  3. Open web/index.html locally to check UI changes.
  4. Check JavaScript console for syntax errors if the page is blank.
  5. Test inside FiveM before deploying broadly.

If your edits break the page, compare your file against the unmodified config.js from the release archive.

6. Server branding and text​

Find the server section in web/config.js:

server: {
    name: 'Sunset Roleplay',
    shortName: 'SRP',
    tagline: 'Every story matters.',
    description: 'Community-driven roleplay, meaningful careers, and memorable events.',
    logo: 'assets/logo-placeholder.svg',
    statusText: 'Establishing connection'
},
KeyWhere it appears
nameMain server name and browser title.
shortNameSmall label near the name.
taglineLarge headline.
descriptionSupporting paragraph below the headline.
logoMain image alongside the server name.
statusTextSmall status pill at the top.

The header's status text is static configuration: it does not automatically indicate live server health. Do not claim it reports actual uptime, player count, or maintenance mode without implementing an integration.

For a clean result, keep the tagline relatively short and check longer descriptions at smaller window sizes. The original demo text should be removed before you publish to customers.

Option A: Replace the included SVG​

  1. Create your own SVG logo.
  2. Back up web/assets/logo-placeholder.svg.
  3. Replace it with your SVG using the same name.
  4. Leave server.logo: 'assets/logo-placeholder.svg' as-is.
  5. Reload the browser preview and test in FiveM.

Option B: Use a different SVG​

  1. Copy my-server-logo.svg into web/assets/.

  2. Update the config:

    server: {
        // Keep your other server settings here.
        logo: 'assets/my-server-logo.svg'
    },

  3. SVG files are already included by web/assets/*.svg in the resource manifest.

Option C: PNG or WebP​

Use a file such as web/assets/my-server-logo.png and set:

logo: 'assets/my-server-logo.png',

You must also register the new type in fxmanifest.lua under files, for example 'web/assets/*.png'; the shipped wildcard includes only SVG assets.

Design tips​

  • Prefer a transparent background for your logo.
  • Avoid tiny text in the art, since the logo is displayed at a relatively small size.
  • Keep image size modest to reduce asset download weight.
  • If the logo looks stretched, check the original image aspect ratio and the .brand-lockup__logo CSS selector in web/style.css.
  • Paths are relative to web/, and spelling/capitalization must match exactly.

8. Theme colors and effects​

Edit the theme object in web/config.js:

theme: {
    accent: '#ff3b30',
    accentSecondary: '#ff8a3d',
    text: '#f7f8fb',
    mutedText: '#a9aebb',
    panel: '#0b0d12',
    overlayOpacity: 0.72,
    showGrid: true,
    showGrain: true
},
SettingFunction
accentPrimary highlight, buttons, accents, focus ring, one background glow.
accentSecondarySecondary glow/highlight.
textMain interface text.
mutedTextSecondary/subdued text.
panelInformation panel background.
overlayOpacityStrength of part of the dark background overlay. Intended range 0–0.95.
showGridTurns grid overlay on or off.
showGrainTurns grain/noise overlay on or off.

Example: cooler blue theme​

theme: {
    accent: '#3999ff',
    accentSecondary: '#8a7dff',
    text: '#f8fbff',
    mutedText: '#b3c1d5',
    panel: '#0b1422',
    overlayOpacity: 0.78,
    showGrid: true,
    showGrain: false
},

Implementation detail: v1.0.1 evaluates overlayOpacity with a fallback expression that interprets the numeric value 0 as absent. Setting 0 therefore reverts to 0.72 rather than removing the overlay entirely. To remove it fully, edit .scene__scrim in web/style.css and test contrast/readability. Values greater than 0 work as expected within the clamped range.

For typography, backgrounds, shape, card borders, and positioning beyond these settings, edit CSS rather than inventing additional config keys.

9. Image slideshow backgrounds​

The default loading screen rotates through three local SVG backgrounds. Configure them in:

media: {
    backgrounds: [
        'assets/background-city.svg',
        'assets/background-waves.svg',
        'assets/background-grid.svg'
    ],
    backgroundInterval: 9000,
    video: {
        enabled: false,
        source: 'media/background.mp4'
    }
},

Use your own slideshow images​

  1. Put the new backgrounds in web/assets/ (or in web/media/).

  2. If they are PNG/JPG/WebP in web/assets/, update the manifest files list to include those formats; files under web/media/* are already covered.

  3. Change media.backgrounds to the new relative paths:

    backgrounds: [
        'media/city-night.webp',
        'media/highway.jpg',
        'media/police-station.png'
    ],
    backgroundInterval: 10000,

  4. Set media.video.enabled to false to display the slideshow as the main background.

  5. Test cropping and legibility in different window sizes.

Interval behavior​

  • Values are in milliseconds. 9000 means nine seconds.
  • The code enforces a three-second minimum for slideshow rotation.
  • With only one image, no slideshow rotation occurs.
  • Users who request reduced motion will not see the rotating slideshow.
  • With video enabled, the slideshow is used when video fails to load or play.

For the best appearance, use landscape images with adequate resolution and a restrained file size. The interface uses cover-style cropping, so keep critical parts of your image away from the very edges.

10. Video backgrounds and fallback​

The supplied UI supports an optional local, muted, looping MP4 background.

Set up an MP4 background​

  1. Prepare a compatible, compressed .mp4 file.

  2. Copy it to:

    hsc_loadingscreen/web/media/background.mp4

  3. In web/config.js, set:

    media: {
        backgrounds: ['assets/background-city.svg'],
        backgroundInterval: 9000,
        video: {
            enabled: true,
            source: 'media/background.mp4'
        }
    },

  4. Keep at least one valid path in media.backgrounds for fallback.

  5. Restart/test with an actual FiveM client.

Expected behavior​

  • The HTML video element is muted, loops, and is intended as a decorative full-screen background.
  • The app tries the configured MP4 first. If playback fails, errors, or it is not sufficiently ready after approximately 3.5 seconds, it starts the image slideshow.
  • Video sound is not the music player. Configure audio separately under music.
  • A smaller optimized video reduces player download and load time.

If the video stays black, check the file path, packaging under web/media/*, actual video encoding, and whether the file plays in FiveM's embedded browser. A .mp4 extension alone does not guarantee that the codec is supported.

11. Real FiveM progress and messages​

The progress UI reads FiveM's built-in browser message:

window.addEventListener('message', (event) => {
    if (event.data?.eventName === 'loadProgress') {
        // app.js updates the progress bar using loadFraction * 100.
    }
});

This is an illustrative excerpt of the built-in behavior, not additional code to paste. web/app.js already contains the actual loadProgress listener.

Customize the text shown during loading​

loading: {
    messages: [
        'Preparing your session',
        'Loading the city',
        'Syncing server resources',
        'Finalizing your connection'
    ],
    // Other loading keys continue below.
},
  • These messages change according to the percentage completed, not based on exact resource-specific milestones.
  • For four configured messages, the app displays a message corresponding to each quarter of the progress range.
  • Actual progress values come from FiveM; do not assume each message describes the precise operation being performed.
  • In the local browser preview, a simulated value repeats so you can inspect the UI without connecting to a server.

What not to edit​

Do not hardcode progress percentages in HTML or remove the loadProgress event listener unless you are intentionally rewriting the progress system. server.statusText is a static header label and is not a replacement for the real progress indicator.

12. Community tips​

The tip card displays short messages at an interval you control.

loading: {
    messages: [
        'Preparing your session',
        'Loading the city',
        'Finalizing your connection'
    ],
    tips: [
        'Read our community rules before joining a scene.',
        'Need help? Open a support ticket in Discord.',
        'Use /report if you need staff assistance.'
    ],
    tipInterval: 7000
},

Behavior​

  • tipInterval is in milliseconds, so 7000 is seven seconds.
  • The implementation enforces a minimum interval of three seconds.
  • If there is just one tip, it remains on screen without rotating.
  • If the tips array is empty, the tip card is hidden.
  • Reduced-motion settings disable tip rotation in the supplied player.

Writing useful tips​

Write practical, server-specific tips with short sentences. Avoid huge paragraphs, sensitive information, or commands that your server does not actually provide. The text is fixed in the configuration; it is not fetched dynamically from Discord or another service.

13. Information panels overview​

The right-hand information area uses four built-in panels: welcome, features, rules, and team. Each panel has its own content and enabled switch.

panels: {
    autoRotate: true,
    interval: 8500,
    welcome: { enabled: true, /* more settings */ },
    features: { enabled: true, /* more settings */ },
    rules: { enabled: true, /* more settings */ },
    team: { enabled: true, /* more settings */ }
},

The snippet is only a structural illustration. Preserve the full content in your shipped config.js when editing.

  • Players can click each visible tab using the loading screen cursor.
  • autoRotate: true automatically changes panels when more than one is enabled.
  • autoRotate: false leaves tabs interactive but disables automatic panel changes.
  • interval is in milliseconds; rotation uses a minimum of 4,000 ms.
  • Automatic rotation is disabled for users who request reduced motion.
  • If all four panels are disabled, the information card is hidden.

Display limits in v1.0.1​

Data typeMaximum rendered
Welcome stats3
Feature items4
Rule items5
Team members4

Extra data is ignored by the current renderer. To display more than these limits, you must modify web/app.js and potentially the layout CSS; adding extra items to the configuration alone will not display them.

14. Welcome panel and stats​

The Welcome panel is designed to introduce the city and highlight a few quick facts.

welcome: {
    enabled: true,
    label: 'Welcome',
    eyebrow: 'Welcome to the city',
    title: 'Make this city your home.',
    body: 'Choose your path, meet your neighbors, and build your character.',
    stats: [
        { value: '24/7', label: 'Community' },
        { value: '40+', label: 'Activities' },
        { value: 'Active', label: 'Support' }
    ]
},

Change this block inside panels in the main config.

KeyMeaning
enabledShow or hide the panel.
labelText on its clickable tab.
eyebrowSmall introductory text.
titleMain panel heading.
bodySupporting paragraph.
statsList of value/label pairs (first three visible).

The stats are static. For example, writing 200 next to Players is not a live player count. Only display claims that are accurate for your server; an automatic statistics integration would require additional development.

15. Features and rules panels​

Features​

Edit the panels.features object:

features: {
    enabled: true,
    label: 'Features',
    eyebrow: 'Discover the city',
    title: 'Play your story.',
    items: [
        { title: 'Player businesses', text: 'Build a business with other players.' },
        { title: 'Emergency services', text: 'Join police, EMS, or fire roles.' },
        { title: 'Civilian careers', text: 'Find a career and earn your reputation.' }
    ]
},

The first four items appear. Each is displayed with a numbered marker, feature title, and description.

Rules​

Edit panels.rules:

rules: {
    enabled: true,
    label: 'Rules',
    eyebrow: 'Community standards',
    title: 'Respect the roleplay.',
    items: [
        'Treat other players respectfully.',
        'No RDM or VDM.',
        'Do not metagame or exploit bugs.',
        'Use the proper channels for support.'
    ]
},

The first five rules are shown. These are highlights rather than a substitute for your full rules page. If your server's policies change, remember to update this list manually.

Disable either section​

Set enabled: false inside the corresponding object. A disabled panel disappears from the tab list and from automatic rotation.

16. Team panel​

Use the team panel to introduce server leadership or staff roles:

team: {
    enabled: true,
    label: 'Team',
    eyebrow: 'Meet the people',
    title: 'Our community team.',
    members: [
        { name: 'Server Owner', role: 'Founder', initials: 'SO' },
        { name: 'Lead Developer', role: 'Development', initials: 'LD' },
        { name: 'Support Team', role: 'Community Support', initials: 'ST' }
    ]
},

Each team member is rendered as initials, name, and role. The first four entries appear. Individual avatar portraits are not part of the built-in team panel; replacing initials with portraits would require HTML/CSS/JavaScript customization.

The team list is not automatically linked to Discord roles. Make manual changes to keep it accurate after team promotions or departures. Leave off private contact information unless the person has consented to its publication.

Set your community links under the top-level socials array:

socials: [
    { label: 'Discord', value: 'discord.gg/YOURCODE', url: 'https://discord.gg/YOURCODE' },
    { label: 'Store', value: 'store.example.com', url: 'https://store.example.com' },
    { label: 'Website', value: 'example.com', url: 'https://example.com' }
],
FieldWhat it does
labelShort label above the link value.
valueText displayed to users.
urlDestination opened when the user clicks.

Behavior and limits​

  • The first four entries are displayed.
  • Links must begin with http:// or https:// to become clickable; otherwise the item is plain text.
  • The interface uses links with target="_blank" and rel="noopener noreferrer".
  • Actual external-link behavior can depend on FiveM's embedded browser environment; verify it with a client.
  • A link is not automatically validated or checked for availability.

Never leave another server's example Discord invite or store URL in a customer deployment. Use URLs you administer or trust. For good usability, keep value short even if url is long.

18. Music player basics and controls​

The music player appears only when:

  1. music.enabled is not set to false; and
  2. At least one valid track is present in music.tracks.

Standard music settings​

music: {
    enabled: true,
    autoplay: true,
    volume: 0.35,
    loadTimeoutMs: 15000,
    skipOnError: true,
    tracks: [
        { title: 'Night Drive', artist: 'Artist', source: 'media/night-drive.mp3' }
    ]
},
SettingPurpose
enabledfalse hides and disables the player.
autoplayAttempts to play at load; restricted browsers might require a click.
volumeStarts between 0.0 and 1.0. v1.0.1 correctly accepts 0.
loadTimeoutMsTime allowed for loading/buffering, clamped from 3,000 to 60,000 ms.
skipOnErrorIf enabled, skips an unavailable song (after optional fallback).
tracksPlaylist array of local tracks and/or direct hosted audio URLs.

Built-in controls​

  • Previous / Play-Pause / Next buttons.
  • Mute/unmute and volume slider.
  • Track title and optional artist.
  • Playback status, such as Playing, Paused, Buffering…, or an error message.
  • Space: play/pause; M: mute; Left/Right: previous/next track.

Keyboard shortcuts only act when the music UI is active and the user is not typing or interacting with an input/button/link. Actual key behavior can depend on the embedded browser having focus.

Stop showing the player​

Set enabled: false or clear the tracks array (tracks: []). Music is not automatically available just because the player is enabled—you must configure tracks.

19. Adding local music files​

Local files are the most reliable option when you need audio to work without third-party hosting.

Installation steps​

  1. Prepare an audio file you are allowed to use (MP3 or OGG are sensible starting formats).

  2. Copy it to hsc_loadingscreen/web/media/.

  3. Add it to the music.tracks array in web/config.js:

    tracks: [
        { title: 'Loading Theme', artist: 'Server Soundtrack', source: 'media/loading-theme.mp3' },
        { title: 'After Hours', artist: 'Server Soundtrack', source: 'media/after-hours.ogg' }
    ]

  4. Make sure music.enabled: true.

  5. Reload the preview and reconnect to FiveM.

The provided manifest includes web/media/*, so files placed directly in that directory are covered without additional entries. The configured filename must match the real filename exactly.

Tips​

  • Avoid oversized lossless files unless you have a specific reason.
  • Keep bitrate and track length practical for connection time and resource downloads.
  • If local playback fails, check the file extension, codec, capitalization, and browser console.
  • You can mix local audio and online URLs in one playlist.

Copyright: Only use audio you created or have rights to stream/distribute. A publicly accessible file is not automatically licensed for use on your server.

20. Playing music from a URL​

Introduced/improved in v1.0.1: Music entries accept source, url, or link, and they can also be written as simple strings.

Example: direct audio files​

music: {
    enabled: true,
    autoplay: true,
    volume: 0.35,
    loadTimeoutMs: 15000,
    skipOnError: true,
    tracks: [
        {
            title: 'City Nights',
            artist: 'Your Artist',
            url: 'https://cdn.example.com/music/city-nights.mp3'
        },
        {
            title: 'Loading Mix',
            artist: 'Your Artist',
            link: 'https://audio.example.com/files/loading-mix.ogg'
        }
    ]
},

The example domains above are placeholders and will not play as written. Replace them with direct playable endpoints that you control or are licensed to use.

  • It returns actual audio bytes/a stream, not an HTML music page.
  • HTTPS is strongly recommended. HTTP links can be blocked as mixed content inside an HTTPS context.
  • The host supports external embedded playback; some providers prevent hotlinking or require authentication.
  • A compatible audio codec is supplied, ideally MP3 or OGG, with an appropriate MIME type such as audio/mpeg.
  • The audio endpoint does not have to end in .mp3 if its response is a playable audio stream.

Unsupported page links​

Do not paste ordinary YouTube watch/share URLs, Spotify song pages, SoundCloud song pages, Apple Music pages, Google Drive viewing links, or login-protected file sharing pages. These are not direct audio files. The player identifies several common page-link patterns and reports an error rather than trying to extract their audio.

Simple string syntax​

tracks: [
    'https://your-domain.example/audio/first.mp3',
    'media/second-song.mp3'
]

For string entries, the player generates a basic title such as Track 1. Use objects if you want polished metadata and fallbacks.

21. Internet radio and streaming endpoints​

A radio station can work if it provides a direct stream URL compatible with the browser's HTML audio element. A station's homepage, widget page, or playlist directory URL is not necessarily playable.

Example​

tracks: [
    {
        title: 'Live Community Radio',
        artist: 'Your Radio Station',
        link: 'https://radio.example.com/stream'
    }
]

The URL is an illustrative placeholder. Substitute an actual audio endpoint from your streaming provider. The stream can have a path such as /stream rather than a file extension as long as the response contains playable audio.

Stream-specific notes​

  • A continuous live stream usually does not naturally end, so the player will not progress to the next track until the user skips or the stream errors.
  • The built-in player does not automatically fetch live track artwork, artist metadata, or station history.
  • HLS (.m3u8) and other stream/container formats are not guaranteed to be supported by FiveM's embedded browser. Test the exact endpoint and codec before advertising support.
  • The host needs to allow external client connections from players' networks.
  • Radio streaming availability and buffering are outside the resource's control.

For a station hosted through AzuraCast or another radio platform, use the service's actual direct audio mountpoint, not its public web-player page. The correct mountpoint varies per station and should be checked with your hosting configuration.

22. Fallback tracks, timeouts and errors​

A remote link may be blocked, offline, or too slow. The v1.0.1 player supports local fallback and automatic skipping.

Fallback example​

tracks: [
    {
        title: 'Main Theme',
        artist: 'Your Artist',
        url: 'https://cdn.example.com/audio/main.mp3',
        fallbackSource: 'media/main-backup.mp3'
    },
    {
        title: 'Second Track',
        artist: 'Your Artist',
        source: 'media/second.mp3'
    }
]

fallbackUrl is an accepted alternative to fallbackSource. Use one or the other. The fallback can be a local source or a direct hosted audio endpoint, but a local fallback protects you against internet outages of the primary host.

How recovery works​

  1. Player loads the primary source / url / link.
  2. If loading or playback fails, it attempts fallbackSource / fallbackUrl, when configured.
  3. If the fallback also fails and skipOnError: true, it moves to the next unfailed track.
  4. If every track fails, or skipOnError: false, it stops and displays an error.

Timeout setting​

loadTimeoutMs: 15000,
skipOnError: true,
  • 15000 means 15 seconds.
  • The accepted effective range is 3–60 seconds.
  • This guards against slow initial loading and certain buffering stalls; it is not a guarantee every network issue will be detected.

Common status messages​

Status shownMeaning / next step
Connecting to audio link…Attempting to load remote audio.
Loading audio…Attempting to load a local source.
Ready to playAn audio source was prepared and is not currently playing.
PlayingThe selected audio is actively playing.
Buffering…Waiting for playable media data.
Click play to enable audioBrowser blocked autoplay; interact with player.
Use a direct audio link, not a webpageA known music-page URL was rejected.
Audio unavailable — check the link or hostThe selected source/fallback could not be played.

In the browser console, player warnings start with [HSC Loading Screen]. A successful FiveM server start does not prove a remote audio URL will work for players.

23. Music keyboard shortcuts and autoplay​

Keyboard shortcuts​

KeyEffect
SpacePlay or pause.
MMute or unmute.
Left ArrowPrevious track.
Right ArrowNext track.

Shortcuts only work when the player is active and the embedded webpage has keyboard focus. They are intentionally ignored for repeated keydown events, modifier-key combinations, and while focus is in an input, button, or link. In-game behavior can vary based on FiveM input focus.

Autoplay behavior​

autoplay: true,

This tells the app to attempt playback as soon as the player initializes. It does not override Chrome/CEF autoplay policies. If the browser blocks playback, users can click the Play button after the page gains focus.

To require a manual action instead:

autoplay: false,

To start silently but leave controls visible:

volume: 0,

In this version, volume: 0 is handled correctly. A muted or zero-volume player is still an initialized player; disable the music section if you want no playback attempts or player UI at all.

24. Visual layout and advanced CSS​

Most visual changes belong in web/config.js. For advanced work, edit web/style.css and preview before deploying.

Useful selectors​

CSS selectorElement
.shellFull-page main grid and padding.
.topbarUpper status and social links.
.status-pillConnection status badge.
.brand-lockup__logoLogo sizing.
.hero__taglineMain headline text.
.progress-card, .progress-trackLoading UI.
.tip-cardTip card.
.info-card, .panel-tabInformation panel and tabs.
.music-player, .icon-buttonAudio controls.
.scene__scrimDark background overlays.
.scene__glowDecorative color glows.

Example: change font stack​

The supplied stylesheet defines a --font CSS variable. To change it, edit the :root declaration, for example:

:root {
    --font: "Segoe UI", Arial, sans-serif;
}

This example uses locally available system fonts and has no third-party font download requirement.

Example: slightly smaller server title​

.brand-lockup h1 {
    font-size: 24px;
}

Append overrides at the end of web/style.css, rather than changing app.js for purely visual edits.

Responsive considerations​

  • The stylesheet includes layout changes for narrow viewports and shorter screen heights.
  • At widths under ~760px, the information card moves below the main hero content.
  • The media queries and reduced-motion behavior should be preserved when customizing.
  • Backgrounds are scaled/cropped to fill the viewport; use assets with a safe focal area.
  • Check that the music controls and social labels do not collide at 720p and on unusual aspect ratios.

If you add new UI elements to web/index.html, you will likely need corresponding CSS. The guide does not claim they are configurable from config.js automatically.

25. Browser preview and FiveM testing​

Test locally​

  1. Open hsc_loadingscreen/web/index.html in Chrome, Edge, or a similar browser.
  2. Confirm the logo, colors, text, backgrounds, panel content, and social links.
  3. The app simulates loading progress when opened by file:// or on localhost / 127.0.0.1.
  4. Try the music controls; remote audio playback may behave differently in the local browser versus FiveM.
  5. Inspect developer tools (usually F12) for missing files and JavaScript errors.

The preview percentage is simulated and loops: it is not a live connection to your server.

Test in FiveM​

  1. Install the resource and ensure it in server.cfg.
  2. Reconnect using a real FiveM client; a refresh of a running browser tab is not a substitute.
  3. Confirm that the progress bar responds during the join sequence.
  4. Check UI positioning at your usual game display resolution.
  5. Verify local music, online music, fallback behavior, and player controls.
  6. Test a deliberately broken audio URL in a staging copy, then restore the real playlist.
  7. Confirm that the loading screen closes normally after joining.
  • No JavaScript console errors.
  • All expected images/video load, or the fallback is shown.
  • No placeholder server name, invite, store URL, or staff member remains.
  • Music is audible when permitted and does not start at an excessive volume.
  • No oversized media slows the resource download.

26. Troubleshooting common issues​

Use this table to isolate problems before editing core code.

ProblemWhat to check
Loading screen never appearsResource folder naming, ensure hsc_loadingscreen, fxmanifest.lua location, competing loadscreen resources, startup errors.
Blank/black UIJavaScript syntax error in web/config.js, missing index.html, script path issues, browser console logs.
Background stays blackImage path incorrect, asset omitted from files, video failed without a valid fallback image.
New PNG/WebP logo is missingAdd PNG/WebP entries to fxmanifest.lua files list and confirm actual path.
Music section not visiblemusic.enabled may be false or music.tracks may be empty/invalid.
MP3 URL does not playConfirm direct playable audio, HTTPS, MIME type, permissions, host restrictions, and codec.
YouTube/Spotify link failsThese are webpage links, not direct audio endpoints. They are unsupported by this player.
Track is stuck on connectingVerify URL availability, adjust loadTimeoutMs if justified, add fallbackSource.
Autoplay failsClick Play; browsers can block autoplay without user interaction.
Music plays locally, not in FiveMCEF/client restrictions, codecs, URL access, HTTPS, and server response headers.
Only some features/rules showRenderer limits: 4 features and 5 rules in this version.
Staff list won't update automaticallypanels.team.members is static configuration.
Progress works in browser but not FiveMBrowser progress is simulated. Verify real resource activation and loadProgress event behavior.
Social item is not clickablesocial.url must start with http:// or https://.
Changes don't showVerify edited folder, resource restarted, and reload/reconnect; check client caching.
Screen remains after joiningCheck for competing loadscreen logic; manual shutdown is not configured in this release.

Debug order​

  1. Confirm ensure hsc_loadingscreen succeeded server-side.
  2. Open web/index.html and inspect the browser console.
  3. Restore a known-good copy of web/config.js if you see a syntax error.
  4. Confirm your asset exists and is included in fxmanifest.lua.
  5. Reduce to a single packaged SVG background and one packaged MP3 to test without external hosting.
  6. Test again in FiveM and record the exact symptom/client log before changing application logic.

For a failed hosted audio link, open the exact direct URL, not the vendor's share page, and check whether it actually returns playable media. Some services restrict hotlinking or require cookies/authentication.

27. Updating from v1.0.0 to v1.0.1​

Version 1.0.1 focuses on online music compatibility and audio error handling. The existing local source: 'media/...' track format remains supported.

Changes introduced​

  • music.tracks accepts source, url, link, or a string URL/path.
  • Direct online audio files and compatible streams are handled alongside local files.
  • fallbackSource / fallbackUrl supports secondary audio sources.
  • Configurable music.loadTimeoutMs and music.skipOnError.
  • Playback status feedback for failures, loading, and buffering.
  • Detection of several common music-page URLs that are not playable audio.
  • Correct handling of initial volume: 0.
  • Music keyboard shortcuts do not fire while interacting with controls.
  1. Stop the resource or server.
  2. Back up the entire existing hsc_loadingscreen folder.
  3. Save copies of your custom web/config.js, web/style.css, logos, and web/media content.
  4. Replace the resource with the v1.0.1 release.
  5. Merge your previous server information, themes, panels, socials, and music into the new web/config.js. This retains the new timeout and fallback settings.
  6. Restore your actual custom assets and any needed manifest additions.
  7. Reapply custom CSS carefully—do not overwrite the new music status styles with an outdated stylesheet.
  8. Start the resource, preview it, and reconnect from FiveM.

Avoid replacing only web/config.js with an older version without checking the new fields. The v1.0.1 runtime supports many old settings, but using the current config template makes troubleshooting much simpler.

28. Developer reference and limitations​

This section describes the current shipped implementation, not a promise of a public plugin API.

Entry points​

  • fxmanifest.lua registers loadscreen 'web/index.html' and loadscreen_cursor 'yes'.
  • web/index.html loads style.css, config.js, and app.js with defer.
  • web/config.js creates window.HSC_LOADING_CONFIG.
  • web/app.js initializes the theme, branding, socials, backgrounds, progress, tips, panels, music, keyboard controls, FiveM listener, and local browser preview.

FiveM progress event​

The player listens to window messages named loadProgress and treats loadFraction as a fractional value from 0 to 1:

// Illustrative payload shape received from FiveM:
{
    eventName: 'loadProgress',
    loadFraction: 0.5
}

The existing code translates this into 50%. It also clamps progress to the 0–100% range. You do not need to add client or server Lua events to get the basic loading progress.

Current boundaries​

  • The information panels support four renderer types: welcome, features, rules, and team.
  • The order is fixed by web/app.js; additional panel keys are not automatically recognized.
  • Static config cannot fetch staff roles, player counts, or Discord updates by itself.
  • The music player uses new Audio(), not an embedded iframe/player SDK. Playlist entries must resolve to directly playable media.
  • The source uses standard frontend JS/CSS and does not expose a stable exported developer API for other FiveM resources.
  • Manual shutdown is not enabled in the shipped fxmanifest.lua. Do not add loadscreen_manual_shutdown 'yes' without implementing and testing corresponding shutdown behavior.

Where to edit for new features​

Desired featureLikely files
Extra information panel typeweb/app.js, web/config.js, web/style.css
New header/footer elementweb/index.html, web/style.css, optionally web/app.js
Different progress behaviorweb/app.js (advanced)
Different audio backendweb/app.js, possibly web/index.html and dependencies
New asset format/pathfxmanifest.lua and config references

When modifying application logic, test all playback and panel paths. This product is intentionally lightweight rather than a framework-dependent dashboard.

29. Performance and production checklist​

Use this checklist before distributing or deploying a customer-branded build.

Branding and content​

  • Server name, short name, tagline, description, and logo are correct.
  • Top-level social URLs point to the intended server/store.
  • Welcome stats and feature claims are accurate.
  • Rules and team membership are current.
  • Credit text visibility matches your license/branding agreement.

Media and performance​

  • All referenced local files exist and are packaged by fxmanifest.lua.
  • Video has been compressed and has an image fallback.
  • All playlist tracks are playable and legally usable.
  • External audio uses HTTPS direct endpoints; a local fallback is configured where needed.
  • Failed URLs do not leave a broken experience (test skipOnError).
  • Audio starts at an appropriate volume.

Compatibility and QA​

  • ensure hsc_loadingscreen is present in server.cfg.
  • No competing loading-screen resource is active.
  • UI has been checked at common client resolutions.
  • Real FiveM progress updates correctly during a fresh join.
  • Keyboard and mouse music controls work in a real FiveM client.
  • Reduced-motion appearance is acceptable.
  • No JavaScript errors or missing-asset warnings remain.

Updating and handoff​

  • Customer's web/config.js was backed up.
  • Existing custom CSS and files were merged rather than blindly overwritten.
  • Installation instructions accompany the delivered resource.
  • Any external audio/video services and recurring hosting costs are disclosed to the customer.

30. FAQ​

Does it require QBCore or ESX?​

No. It is standalone and works independently of roleplay frameworks.

Can I customize it without knowing JavaScript?​

For normal settings, yes: replace names, text, links, colors, images, and configured arrays in web/config.js. You still need to preserve valid JavaScript syntax. Structural UI changes require CSS/JS knowledge.

Yes, if the URL points to compatible playable audio and its host permits direct remote playback. Test in FiveM.

Not as the audio source in v1.0.1. Those song pages are not direct audio streams and the player does not extract/convert them.

Can I use an internet radio stream?​

Potentially, yes, when it is a directly playable compatible audio endpoint. The station website itself is not the endpoint; codec/stream support should be tested in the client.

Why does music.enabled: true show no player?​

The player also requires at least one valid entry in music.tracks.

Can I disable music entirely?​

Yes. Set music.enabled: false or leave tracks: [].

Can I hide the animated grid/grain?​

Yes. Set theme.showGrid: false and/or theme.showGrain: false.

Can I replace slideshow images with a video?​

Yes. Add a compatible local MP4 under web/media, set media.video.enabled: true, and set media.video.source appropriately. Keep an image fallback.

Can I add more staff than four?​

Not through config alone in this version. The current renderer displays only the first four team members.

Will my staff roster, player count, and server status automatically update?​

No. Values in the config are static. Such live integrations would need additional code.

Can I remove the product credit?​

The setting product.showCredit controls whether the credit appears in the UI. Whether you are contractually permitted to remove it depends on your license or agreement with the distributor.

Does browser preview show true server loading?​

No. The local preview animates simulated progress. A FiveM client supplies the live loadProgress event.

Why don't my new image files appear in FiveM?​

Check relative paths and the manifest. The default asset wildcard includes SVG files, not new PNG/WebP files under web/assets unless you add their patterns. Local media in web/media/* is included.

31. Support and release information​

Product: HSC Loading Screen
Publisher: Hotspot Creations
Documented version: 1.0.1
Platform: FiveM (standalone loading screen)
Primary configuration: web/config.js

Before requesting support, prepare:

  1. The documented product version and whether you modified core files.
  2. Your FiveM server artifact version if the issue appears client-specific.
  3. The exact error message or screenshot of the failing UI.
  4. Relevant console logs, especially messages prefixed [HSC Loading Screen].
  5. The relevant part of web/config.js with passwords, tokens, and private URLs removed.
  6. Whether the issue happens in local browser preview, in FiveM, or both.
  7. The type of media source (packaged MP3, direct HTTPS audio, live stream, or MP4 background).

For release notes, see the bundled CHANGELOG.md. For a simpler original setup reference, see the bundled README.md and CUSTOMIZATION.md.

Media and licensing: Use only images, music, videos, and third-party streams for which you have permission. Protect customer server information and avoid publishing private tokens in web/config.js, which is delivered to client browsers.