All resources

rsg-loading — Technical Docs#

Contents#

  1. Architecture
  2. Config sources
  3. Theme selection
  4. NUI messages
  5. Closing the loading screen
  6. Locales
  7. Security
  8. Troubleshooting

1. Architecture#

FileRole
fxmanifest.luaDeclares loadscreen 'html/index.html' with loadscreen_manual_shutdown 'yes'. Loads @rsg-core/shared/locale.lua for the server version checker.
config.luaLanguage and seasonal themes. Never executed as Lua by the screen — html/script.js fetches it and parses it with a small Lua-literal parser. Plain values only.
html/config.jsonBackground, dim, tip interval, auto-close timeout.
html/script.jsLoads config + locale, picks a theme, drives progress, tips, particles and closing.
html/style.cssHouse style (Roboto, monochrome panel); theme colours are CSS variables overridden at runtime.
locales/*.jsonAll text; shared by the screen (ui_*, theme_*) and server console (sv_*).
client/client.luaOn RSGCore:Client:OnPlayerLoaded (if Config.CloseOnPlayerLoaded) sends endLoading and calls ShutdownLoadingScreenNui().
server/server.luaOn playerConnecting (if Config.ServerInfo) calls deferrals.handover({ rsgLoading = { players, maxPlayers, serverName } }). The screen reads it from window.nuiHandoverData. Server name = sv_projectName, else sv_hostname, with ^n colour codes removed.
html/fonts.css, html/fonts/Bundled Roboto (latin, latin-ext, greek; 400/500/700 + 400 italic). Japanese falls back to system fonts.
server/versionchecker.luaCompares version in fxmanifest with rsg-versioncheckers/main/rsg-loading/version.txt.

No database, no exports, no callbacks. config.lua is also loaded as a shared script so client/server Lua can read it.

2. Config sources#

  • config.lua parser supports: Config = {}, Config.A.B = value, strings (', ", [[ ]]), numbers, booleans, nil, nested tables, -- and --[[ ]] comments. Functions, variables and expressions are ignored/return null.
  • html/config.json keys: background_image (string or list), background_dim (0–1), tip_interval_seconds, auto_close_seconds (0 = off), slideshow_seconds (0 = no rotation), music, music_volume (0–1), discord.
  • Config.ParticleDensity scales particle counts and fireworks frequency (0.1–1). prefers-reduced-motion caps it at 0.3.
  • A theme's background / backgroundDim override the config.json values while it is active.

3. Theme selection (pickTheme)#

  1. Config.Theme = 'default' or 'none' → no theme.
  2. Any other non-auto value → that key from Config.Themes or Config.Seasons.
  3. auto → first enabled entry of Config.Themes whose window contains today (player's local clock), then Config.Seasons if Config.UseSeasons ~= false.

Windows are MM-DD, inclusive, may wrap the year. Feb 29 counts as Feb 28 when a window finishes on 02-28. Easter (no start) uses the Anonymous Gregorian algorithm ± easterDaysBefore / easterDaysAfter.

Holiday order matters only if windows overlap: Lua table key order is preserved as written.

4. NUI messages#

MessageEffect
{ loadFraction = 0..1 } (native)Sets real progress; stops simulated progress.
{ eventName = 'endLoading' } or { type = 'endLoading' }Finishes and closes the screen.
{ statusText = '...' }Replaces the status line.
SendLoadingScreenMessage(json.encode({ statusText = 'Loading world…' }))
SendLoadingScreenMessage(json.encode({ type = 'endLoading' }))

5. Closing#

finishLoading() runs once: stops all timers, particles and the slideshow, fades out music, shows ui_status_ready, then calls invokeNative('shutdownLoadingScreenNui') after 400 ms. Triggered by endLoading (sent by client/client.lua on player loaded) or the auto_close_seconds timeout. A character-selection script may call ShutdownLoadingScreenNui() earlier; calling it twice is harmless.

6. Locales#

Screen language = Config.Locale; missing keys fall back to en.json. Tips are collected from ui_tip_1, ui_tip_2… stopping at the first gap. Theme text: theme_<name>_subtitle, theme_<name>_tip_N. News panel: ui_news_title + ui_news_N (hidden when there are none). ui_players takes two %s (players, max). ui_music_hint shows only when music is set. All 11 languages ship with identical keys: en, de, el, es, fr, ja, nl, pl, pt-br, ro, ru.

7. Security#

The loading screen handles no money, items or player data. All text is inserted with textContent (no HTML injection). Background URLs come only from server-owned config files.

8. Troubleshooting#

ProblemFix
Screen never appearsOnly one resource may declare loadscreen; remove others.
Closes before character selectRaise or disable auto_close_seconds; close it from Lua instead.
Never closesSomething must send endLoading or call ShutdownLoadingScreenNui; keep auto_close_seconds > 0.
Theme not appliedCheck Config.Theme, enabled, date format MM-DD, and that config.lua has no functions/expressions.
Text blankConfig.Locale must match a file in locales/.
No player countConfig.ServerInfo = true; the handover only exists when joining a real server, not in a browser preview.
Music silentCheck the music path (inside html/), music_volume > 0, and that the file is .ogg/.mp3. SPACE toggles it; key input may not reach the screen on every client build.
Slow first paintCompress backgrounds (~200–400 KB JPEG at 1920×1080).

Support the Project : https://rexshack.tebex.store/

<!-- BEGIN AUTO-REFERENCE (generated from the code; re-run the generator instead of editing by hand) -->

Technical reference#

Generated from the source of rsg-loading 3.0.4. Names, arguments and defaults below are read straight from the code.

Dependencies#

rsg-core

Configuration#

OptionDefaultNotes
Config.Locale'en'theme_<name>_tip_1, _tip_2 ... tips for a holiday/season theme
Config.Theme'auto''winter' / 'spring' / 'summer' / 'autumn' = force that season theme all year
Config.ParticlestrueParticle effects (snow, bats, petals, leaves, fireflies, fireworks). Set false to disable on all themes.
Config.ParticleDensity1.0Particles are also reduced automatically when the OS has "reduce motion" turned on.
Config.CloseOnPlayerLoadedtrueSafe to leave on even if your character script also closes it.
Config.ServerInfotrueSend live server info (player count / max players / server name) to the loading screen.
Config.Themestable
Config.MergeTipstrueWhen true, seasonal tips are added to your normal tips. When false they replace them.
Config.UseSeasonstrue
Config.Seasonstable

Locales#

Language files in locales/: de, el, en, es, fr, ja, nl, pl, pt-br, ro, ru. Set the language with setr rsg:locale "en".

<!-- END AUTO-REFERENCE -->