# gh05t Loadingscreen SETUP GUIDE

> This guide is written for buyers and can be published to a knowledge base (GitBook, Tebex docs, etc.). Everything is configured in a **single file** — `html/config.js`. You never need to touch any other file.

**Version:** v2.7.0 · **Support:** [discord.gg/P2FzySeNtv](https://discord.gg/P2FzySeNtv)

## Before You Start

Make sure you have:

* FiveM server access (txAdmin or direct server files)
* The downloaded resource ZIP from Tebex
* A text editor (VS Code recommended)

{% hint style="info" %}
You can preview the whole loading screen in a normal web browser before touching your server — just open `html/index.html`. All visuals, the music player, mini-games, map and menus work. Only FiveM-specific events (real progress bar %, live player list) won't fire.
{% endhint %}

{% stepper %}
{% step %}

## Extract & Place the Resource

1. Open the ZIP you downloaded from Tebex.
2. Extract the folder inside — it must be named `gh05t-loadingscreen`.
3. Move it into your server's `resources/` folder:

   ```
   your-server/
   └── resources/
       └── gh05t-loadingscreen/   ← place it here
   ```

{% endstep %}

{% step %}

## Add to `server.cfg`

Open `server.cfg` and add this line **at the very top**, before any other `ensure` lines:

```cfg
ensure gh05t-loadingscreen
```

{% hint style="info" %}
It must be first — FiveM loads the loading screen before everything else.
{% endhint %}
{% endstep %}

{% step %}

## Open `config.js`

Navigate to:

```
gh05t-loadingscreen/html/config.js
```

This is the **only file you need to edit**. Each section below matches a block in that file.
{% endstep %}

{% step %}

## Choose Your Theme

The theme color drives **everything** — every panel, banner, button, menu, scrollbar, the mini-games, matrix rain and particles all recolor to match.

```js
const theme = "gh05t-green";
```

| Value          | Color                    |
| -------------- | ------------------------ |
| `gh05t-green`  | Neon green (default)     |
| `gh05t-red`    | Red                      |
| `gh05t-gold`   | Gold / yellow            |
| `gh05t-pink`   | Hot pink                 |
| `gh05t-blue`   | Cyan blue                |
| `gh05t-purple` | Purple                   |
| `gh05t-toxic`  | Radioactive yellow-green |
| {% endstep %}  |                          |

{% step %}

## Background Wallpaper (optional)

Show a full-screen image behind everything. Turn it on and pick a mode:

```js
const enableBackgroundImage  = true;       // master on/off
const backgroundImageMode    = "theme";    // "theme" or "slideshow"
const backgroundImageOpacity = 0.35;       // 0.0 (invisible) → 1.0 (fully visible)
```

{% tabs %}
{% tab title="Theme mode" %}
Automatically shows the image that matches your selected theme. Put your images in `html/assets/img/` and map them here:

```js
const backgroundImages = {
    "gh05t-green":  "assets/img/green.jpg",
    "gh05t-red":    "assets/img/red.jpg",
    "gh05t-blue":   "assets/img/blue.jpg",
    "gh05t-pink":   "assets/img/pink.jpg",
    "gh05t-purple": "assets/img/purple.jpg",
    "gh05t-gold":   "assets/img/orange.jpg",
    "gh05t-toxic":  "assets/img/toxic.jpg",
};
```

{% endtab %}

{% tab title="Slideshow mode" %}
Cycles images with a smooth fade:

```js
const backgroundImageMode       = "slideshow";
const backgroundImageSlideshowInterval = 6000;   // milliseconds between images
const backgroundSlideshowSource = "theme";       // "theme" = cycle the images above
                                                 // "custom" = cycle your own list below
const slideshowImages = [
    "assets/img/slide1.jpg",
    "assets/img/slide2.jpg",
    "assets/img/slide3.jpg",
];
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Recommended image size: 1920×1080 or larger (`.jpg` or `.png`).
{% endhint %}
{% endstep %}

{% step %}

## Background Video (optional)

A video can play **behind** the wallpaper for extra depth.

{% tabs %}
{% tab title="YouTube (recommended)" %}

1. Pick a video (city / ambient / cinematic works best).
2. Copy the video ID from the URL — the part after `?v=`:

   ```
   https://www.youtube.com/watch?v=4BSZtvqfzWE
                                    ^^^^^^^^^^^  ← this is the ID
   ```
3. Set it in config.js:

   ```js
   const backgroundVideo        = "4BSZtvqfzWE";
   const backgroundVideoBlur    = 3;    // blur 0–10
   const backgroundVideoOpacity = 0.5;  // 0.0–1.0
   const showYTVideo            = true;
   const useLocalVideo          = false;
   ```

{% endtab %}

{% tab title="Local MP4 (alternative)" %}

1. Put your `.mp4` in `html/assets/media/background.mp4`.
2. Set:

   ```js
   const useLocalVideo  = true;
   const localVideoPath = "assets/media/background.mp4";
   const showYTVideo    = false;
   ```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
The video has no separate on-screen buttons. It is controlled by the **Music Player** (next step) — play/pause stays in sync. See `audioPlayerMuteVideo` to decide whether you hear the video's own sound or your own music over it.
{% endhint %}
{% endstep %}

{% step %}

## Music Player (optional)

A collapsible player that docks to the **left or right edge**. Players click the edge handle to slide out album art, track info, a seek bar, volume and prev/play/next controls. Supports `.mp3`, `.ogg`, `.wav`.

```js
const enableAudioPlayer        = true;
const audioPlayerPosition      = "left"; // "left" or "right" — which edge it docks to
const audioPlayerAutoplay      = true;  // start on load
const audioPlayerVolume        = 0.6;   // 0.0–1.0
const audioPlayerLoop          = true;   // loop the playlist
const audioPlayerStartExpanded = true;  // briefly auto-open on load, then tuck away
```

Add your tracks — audio goes in `html/assets/media/audio/`, cover art in `html/assets/img/audio/`:

```js
const audioPlaylist = [
    {
        title:  "GH05T Labs Intro",
        artist: "GH05T Labs",
        src:    "assets/media/audio/GH05T_Labs-intro.mp3",
        cover:  "assets/img/audio/GH05T_Labs-intro.png"
    },
    // add more tracks in the same format
];
```

Using music together with a background video:

```js
const audioPlayerShowVideoThumbnail = true; // show the video as the player's cover art
const audioPlayerMuteVideo          = true; // true  = mute video, play YOUR music over it
                                            // false = keep the video's own sound
```

{% hint style="info" %}
If you set `enableAudioPlayer = false` but a background video is on, the player automatically turns on in **video-only mode** so the video still has play/pause and volume.
{% endhint %}
{% endstep %}

{% step %}

## Twitch Live Banner (optional)

A collapsible "ON AIR" banner that docks to the **left or right edge**. Clicking it opens your Twitch channel.

```js
const enableTwitchIntegration = true;
const twitchChannel           = "yourchannel"; // your Twitch username (no URL)
const twitchBannerPosition    = "left";        // "left" or "right" — which edge it docks to
```

Set `enableTwitchIntegration = false` to hide it.
{% endstep %}

{% step %}

## Server Name & Social Links

```js
const serverName     = "[GH05T] ROLEPLAY";          // your server name
const serverTagline  = "ACCESSING SECURE SERVER";
const serverSubtitle = "THE FUTURE OF ROLEPLAY";
const securityBadge  = "Connection SECURED";

const discord   = "https://discord.gg/YOURCODE"; // leave any link "" to hide that icon
const instagram = "";
const youtube   = "";
const twitter   = "";
const tiktok    = "";
const website   = "";
```

{% endstep %}

{% step %}

## Layout & Positioning

Place the main UI elements wherever you want — no HTML/CSS editing.

**Tab bar position:**

```js
const tabBarPosition = "bottom"; // "bottom" | "left" | "right"
```

**Brand text + floating logo:**

```js
const brandPosition    = "center";  // "center" or "top-left"
const centerLogoEnabled = true;     // floating GH logo at screen center (only when top-left)
const centerLogoSize    = 1;        // 0.5 – 3  (1 = 100px, 2 = 200px, 3 = 300px)
```

**Server info bar:**

```js
const serverInfoPosition = "center"; // "center" | "top-right" | "bottom-right"
```

**Social links:**

```js
const socialPosition = "center"; // "center" | "bottom-left" | "bottom-right"
```

{% hint style="info" %}
The layout is **fully responsive** — it looks correct from 1080p up to 2K / 4K, and elements shrink automatically on smaller screens so nothing overlaps.
{% endhint %}

**Show / hide individual tabs:**

```js
const enabledTabs = {
    staff: true, players: true, stats: true, map: true,
    game: true, achievements: true, chat: true, info: true,
};
```

Set any to `false` to remove that tab from the bar.
{% endstep %}

{% step %}

## Visual Effects

Turn any background effect on or off independently:

```js
const enableMatrixRain        = true; // falling character rain
const enableScanlines         = true; // scan line overlay
const enableCRTEffect         = true; // CRT vignette
const enableCyberGrid         = true; // background grid
const enableParticles         = true; // floating particles
const enableGlitchEffects     = true; // glitch / flicker
const enableHolographicEffect = true; // animated holographic color sweep
```

{% endstep %}

{% step %}

## Staff Team

```js
var staff_team = [
    {
        "name": "YourName",
        "imageLocal": "assets/img/staff/yourname.jpg",
        "image": "https://i.imgur.com/your-backup-photo.jpg",
        "rank": "Owner",
        "status": "online"   // online | busy | away | offline
    },
    // add more members in the same format
];
```

**To add a staff photo:**

1. Use a square image (200×200 px or larger).
2. Name it to match `imageLocal`, e.g. `yourname.jpg`.
3. Place it in `gh05t-loadingscreen/html/assets/img/staff/`.

{% hint style="info" %}
If the local image is missing, the external `image` link is used. If both are missing, a themed avatar is generated from the initials (controlled by `useGeneratedStaffAvatars`).
{% endhint %}
{% endstep %}

{% step %}

## AI Chatbot

The chatbot replies to keywords typed in the CHAT tab. Update the links and rules to your server:

```js
const enableAIChatbot = true;
const chatbotName     = "[GH05T]";

const chatbotResponses = {
    "help":    { en: "Type 'rules', 'discord', or 'staff'.", ar: "...", de: "..." },
    "rules":   { en: "No RDM, No VDM, respect all players.", ar: "...", de: "..." },
    "discord": { en: "Join: discord.gg/YOURCODE",           ar: "...", de: "..." },
    "staff":   { en: "Contact staff with /report.",          ar: "...", de: "..." },
    "ping":    { en: "🏓 Pong!",                              ar: "...", de: "..." }
};
```

Supported languages: **English · Arabic** (auto right-to-left) **· German**.
{% endstep %}

{% step %}

## City Map Markers

Pins shown on the map in the MAP tab:

```js
const enable3DMap  = true;
const cityMapStyle = "neon"; // "neon" | "holographic" | "wireframe"
const cityMapImage = "assets/img/YourMapImage.png"; // your map image in html/assets/img/

const cityMapMarkers = [
    { id: "police",   name: "Police Station", type: "police",   x: 0.62, y: 0.79, callout: "LSPD HQ" },
    { id: "hospital", name: "Hospital",       type: "hospital", x: 0.58, y: 0.77, callout: "St. Fiacre" },
];
```

**Finding x/y coordinates:**

* `x` and `y` are `0.0`–`1.0` relative to the image.
* `x: 0.0` = left, `x: 1.0` = right · `y: 0.0` = top, `y: 1.0` = bottom.
* Find a pixel position in an image editor, then divide by the image width/height.

**Marker types:** `police` · `hospital` · `cityhall` · `fire` · `bank` · `custom`

{% hint style="warning" %}
Use only original, AI-generated, or custom map images — not copyrighted game maps.
{% endhint %}
{% endstep %}

{% step %}

## Server Stats (STATS tab)

These are static values you set yourself. Edit, add, or remove cards freely:

```js
const enableEconomyDisplay = true;

const serverStats = [
    { icon: "💰", label: "Server Economy", value: "$125,000,000" },
    { icon: "👥", label: "Active Players", value: "250"          },
    { icon: "🚗", label: "Vehicles",       value: "1,500+"       },
    { icon: "💼", label: "Jobs",           value: "50+"          },
];
```

{% endstep %}

{% step %}

## Mini-Games

```js
const enableMiniGame = true;
const miniGameType   = "snake"; // "snake" | "flappy" | "shooter" | "none"
```

Players can also switch between Snake / Flappy / Shooter inside the GAME tab. The play area is a fixed widescreen size — no scrolling while playing.
{% endstep %}

{% step %}

## Weather Preview (optional)

Shows live temperature + a weather icon in the bottom stats bar, based on the viewer's location.

```js
const enableWeatherPreview = true;
const weatherApiKey = "YOUR_OPENWEATHER_KEY"; // free key from openweathermap.org/api
```

{% hint style="info" %}
A demo key is included so it works out of the box. For production, get your own free key.
{% endhint %}
{% endstep %}

{% step %}

## Live Activity Feed (optional)

Rotating "toast" cards showing recent server activity. The feed **picks a free corner automatically** so it never overlaps your other elements:

* if `socialPosition = "bottom-right"` → the feed moves to the **bottom-left**
* if `serverInfoPosition = "bottom-right"` → the feed moves to the **top-right**
* otherwise → it stays **bottom-right**

```js
const enableActivityFeed = true;
const activityFeedItems = [
    { player: "John_Doe",   action: "just joined the server",  time: "2m ago" },
    { player: "Jane_Smith", action: "purchased a new vehicle", time: "5m ago" },
];
```

{% endstep %}

{% step %}

## Custom Cursor (optional)

A glowing animated cursor that matches your theme, with hover/click effects, a motion trail and reactive light on buttons. Turn it off to use the normal system cursor.

```js
const enableCustomCursor = true;    // false = normal system cursor
const cursorColor        = "theme"; // "theme" follows your selected theme, OR lock to one:
                                    // "gh05t-green" | "gh05t-red" | "gh05t-gold" | "gh05t-pink"
                                    // "gh05t-blue"  | "gh05t-purple" | "gh05t-toxic"
```

{% endstep %}

{% step %}

## Achievements (RANKS tab)

```js
const enableAchievements = true;
const achievements = [
    { name: "First Steps",      desc: "Join the server", icon: "🏆", unlocked: true  },
    { name: "Social Butterfly", desc: "Join Discord",    icon: "💬", unlocked: false },
];
```

{% endstep %}

{% step %}

## QR Code (INFO tab)

```js
const enableQRCode = true;
const qrCodeURL    = "https://discord.gg/YOURCODE"; // where the QR code points
```

{% endstep %}

{% step %}

## News Ticker

```js
const enableNewsTicker = true; // false = hide the bar completely
const newsItems = [
    "🎉 Welcome to YOUR SERVER NAME!",
    "🚗 New vehicle pack released!",
    "💰 Double XP weekend is LIVE!",
    "🏆 Join our Discord for exclusive rewards!",
];
```

{% endstep %}

{% step %}

## Restart & Test

1. Save `config.js`.
2. In txAdmin or your console run:

   ```
   restart gh05t-loadingscreen
   ```

   (or do a full server restart).
3. Connect to your server — the loading screen will appear.
   {% endstep %}
   {% endstepper %}

## Important — Resource Name

The folder **must** be named exactly `gh05t-loadingscreen`. If you rename it, the script stops itself and prints a red error in the console:

```
╔══════════════════════════════════════════════════════════╗
║        [GH05T] LOADING SCREEN — INVALID RESOURCE NAME    ║
╠══════════════════════════════════════════════════════════╣
║  Resource folder must be named:  gh05t-loadingscreen     ║
║  Current name:  your-wrong-name                          ║
║  Rename the folder and update ensure in server.cfg.      ║
╚══════════════════════════════════════════════════════════╝
```

Fix: rename the folder back and update the `ensure` line in `server.cfg`.

## Update Notifications

When a new version is released, your console shows this on the next restart:

```
╔══════════════════════════════════════════════════════════╗
║       [GH05T] LOADING SCREEN — UPDATE AVAILABLE          ║
╠══════════════════════════════════════════════════════════╣
║  Installed : v2.6.0                                       ║
║  Latest    : v2.7.0                                       ║
║  What's new: Themed cursor, edge docking, smart feed      ║
║  Download  : discord.gg/P2FzySeNtv                       ║
╚══════════════════════════════════════════════════════════╝
```

To update: download the new version from Tebex and replace your resource folder. Your `config.js` settings are backwards compatible — but it's good practice to compare against the new `config.js` so you can enable any newly added options.

## Troubleshooting

| Problem                            | Solution                                                                             |
| ---------------------------------- | ------------------------------------------------------------------------------------ |
| Loading screen not showing         | Make sure `ensure gh05t-loadingscreen` is the **first** ensure in `server.cfg`       |
| Red error about resource name      | The folder was renamed — rename it back to `gh05t-loadingscreen`                     |
| Background image not showing       | Set `enableBackgroundImage = true` and check the image paths/filenames               |
| YouTube video not playing          | Verify the ID is correct and the video is public / not age-restricted                |
| No video controls                  | Video is controlled by the **Music Player** — keep `enableAudioPlayer = true`        |
| Music doesn't autoplay             | Browsers may block autoplay until a click; inside FiveM it plays automatically       |
| Two sounds at once (video + music) | Set `audioPlayerMuteVideo = true` to mute the video                                  |
| Twitch banner not opening          | Set `twitchChannel` to your username only (no full URL)                              |
| Weather shows "N/A"                | API key invalid or rate-limited — get a free key at openweathermap.org/api           |
| Staff photo not showing            | File name must match `imageLocal` exactly (case-sensitive on Linux)                  |
| Map markers in wrong spot          | Recalculate x/y — they must be 0.0–1.0 relative to image size                        |
| Elements overlap on a small screen | They auto-scale; make sure you're on the latest version (v2.7.0+)                    |
| Social buttons not opening         | Fixed in v2.7.0 — update to the latest version                                       |
| No mouse cursor                    | The custom cursor is on; set `enableCustomCursor = false` for the system cursor      |
| Loading screen never closes        | Your spawn system must call `ShutdownLoadingScreen()` + `ShutdownLoadingScreenNui()` |
| Black screen instead of video      | Switch to a local MP4 or try a different YouTube video                               |

## Manual Shutdown (Custom Spawn Systems)

If you use a custom character creation or spawn menu and the loading screen doesn't close, add this to your spawn handler:

```lua
ShutdownLoadingScreen()
ShutdownLoadingScreenNui()
```

## Support

If you're still stuck:

1. Re-check this guide — most issues are a small config typo.
2. Join our **Discord**: [discord.gg/P2FzySeNtv](https://discord.gg/P2FzySeNtv)
3. Open a **#support ticket** with:
   * Your `config.js` file
   * A screenshot of the issue
   * Any errors from the server console

*\[GH05T] Loading Screen v2.7.0 — by GH05T Laps*


---

# 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:

```
GET https://gh05t-labs.gitbook.io/gh05t-labs/resources/gh05t-loadingscreen-setup-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.