> ## Documentation Index
> Fetch the complete documentation index at: https://hedgeem-api.qeetoto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# F103 — Game Loading Screen

> Progress bar loading screen shown while game assets download. Required for all game clients.

# F103 — Game Loading Screen

|            |                                  |
| ---------- | -------------------------------- |
| **Phase**  | 3 — UI & Presentation            |
| **Jira**   | HEDGE-224                        |
| **Status** | v4 ✅ · v5 ✅ · v6 ✅ · v7 ✅ · v8 ✅ |

***

## Business Rule

Every game client must display a branded loading screen with a visible progress indicator while assets are being downloaded. The loading screen must:

1. Appear immediately on page load (before any game content is visible)
2. Show a progress bar that advances in real time as assets load
3. Dismiss automatically and cleanly when the game is ready to play
4. Never leave the player looking at a blank or partially-rendered screen

***

## Technical Design

Each client implements the loading screen differently to suit its rendering architecture:

### v4 — JS / Phaser 2

Phaser 2 sprite-based two-stage state machine:

* **BootState** loads the loading background image and bar sprites
* **PreloadState** calls `this.load.setPreloadSprite(preloadBar)` — Phaser auto-clips the bar width as assets load
* Transitions to GameRun when `load.onLoadComplete` fires

### v5 — UMA / GDK

HTML/CSS overlay injected before the GDK wrapper:

* Shown immediately on page load
* **XHR intercept**: wraps `window.XMLHttpRequest` to count in-flight vs completed requests; maps completion ratio to 30–88% of the bar
* **Slow drip**: auto-increments toward 30% during synchronous JS script loading phase (no XHR trackable)
* **Completion hook**: patches `GDKLoader.showGameFrame()` to fill bar to 100% then fade out (0.5 s opacity transition)
* Original `XMLHttpRequest` restored after dismissal

```html theme={null}
<!-- Overlay structure (game.html) -->
<div id="hl-loading">
  <div class="hl-inner">
    <img src="gdk/2.1.2/gdkBrand/extraLogo.png" class="hl-logo">
    <div class="hl-track"><div class="hl-fill" id="hl-fill"></div></div>
    <div class="hl-label" id="hl-label">Loading…</div>
  </div>
</div>
```

### v6 — Phaser 3 / TypeScript

Phaser graphics bar rendered inside `PreloadScene`, before `GameScene` starts:

* `PreloadScene.preload()` creates a full-screen dark rectangle, logo text, track rectangle, and fill rectangle
* `this.load.on('progress', value => fill.setScale(value, 1))` drives the bar in real time
* `PreloadScene.create()` transitions to `GameScene` — the loading graphics are destroyed automatically

```typescript theme={null}
// PreloadScene.ts (abridged)
this.load.on('progress', (value: number) => {
  fill.scaleX = value;
  label.setText(`Loading… ${Math.round(value * 100)}%`);
});
this.load.on('complete', () => { /* GameScene starts via create() */ });
```

### v7 — Horse Race / HTML+CSS

HTML overlay on `index.html`, dismissed on the `hedgeem:ready` custom event:

* Overlay shown from page load
* `hedgeem:ready` is dispatched by `src/main.ts` when the engine is initialised and the first game state is ready
* On event: bar fills to 100%, overlay fades out (0.4 s)
* No asset XHR tracking needed — v7 has no significant async asset loads

### v8 — Casino / HTML+CSS

Identical pattern to v7: HTML overlay dismissed on `hedgeem:ready`.

***

## Acceptance Criteria

| #   | Criterion                                                                                          |
| --- | -------------------------------------------------------------------------------------------------- |
| AC1 | Loading screen is visible immediately on page load, before any game content renders                |
| AC2 | Progress bar advances continuously — it never stalls at 0% or jumps from 0% to 100%                |
| AC3 | Loading screen dismisses with a smooth fade when the game is ready                                 |
| AC4 | After dismissal, no loading overlay elements remain in the DOM (or are hidden with `display:none`) |
| AC5 | Works on Chrome, Firefox, Safari (desktop and mobile)                                              |

***

## Version Parity

| Version         | Status | Implementation                                   |
| --------------- | ------ | ------------------------------------------------ |
| v4 (JS)         | ✅      | Phaser 2 `setPreloadSprite`                      |
| v5 (UMA)        | ✅      | HTML overlay + XHR intercept + `GDKLoader` hook  |
| v6 (TS)         | ✅      | Phaser 3 `load.on('progress')` in `PreloadScene` |
| v7 (Horse Race) | ✅      | HTML overlay + `hedgeem:ready` event             |
| v8 (Casino)     | ✅      | HTML overlay + `hedgeem:ready` event             |