# Seifur v4

Browser page: https://seifur.vedrid.is/v4/

Download the complete browser and Unreal source: [seifur-v4-source.tar.gz](assets/seifur-v4-source.tar.gz). Dependencies and Unreal Engine are excluded.

**Unreal 5.9 browser experiment:** a separate WebAssembly/WebGPU project is now prepared in `unreal-web/`, with its entry page at [/v4/web/](https://seifur.vedrid.is/v4/web/). It has not been compiled. See [WEBGPU.md](WEBGPU.md) for source-build requirements, the command bridge and artifact deployment. The 5.7 streaming path below is retained separately.

Prepared on 17 November 2026. Production in `/` and versions `/v2/` and `/v3/` have not been modified. This is an initial Unreal implementation and browser companion, not a full port of every production feature.

## What works here

The responsive Icelandic browser page includes an Iceland station overview, measured wind, gust, temperature and precipitation layers, station search, exact selected-station observations, timestamp and stale-data handling, fullscreen controls and an Epic Pixel Streaming client. Missing measurements stay missing. Data refreshes every 60 seconds while the page is visible. Selected station details come from the existing `observations-latest.php` API. Precipitation values have provider-dependent measurement periods; this is not a harmonized rain-rate layer.

The overview is SVG rendered in the browser. It is explicitly labeled as a web overview. It is not Unreal rendering. No stream is configured and no Unreal app is currently running.

## Unreal project included

`unreal/SeifurV4.uproject` targets Unreal Engine **5.7**, with the original Pixel Streaming plugin (not Pixel Streaming 2). The browser dependency is the matching Epic UE5.7 client, pinned to 0.3.3. Match the infrastructure branch to the engine. Do not swap engine, frontend or infrastructure versions independently.

The C++ project contains:

- A geographically positioned, simplified Iceland coastline, ocean and coordinate grid.
- Native 3D station markers colored by measured weather, directional wind arrows, selected station highlighting and a station label.
- HTTP observation refresh and age checks. Failed refreshes preserve dated observations; markers with missing values for the active layer are omitted.
- Mouse orbit, scroll zoom, WASD pan, Home reset, touch orbit, pinch zoom and station picking.
- Browser-to-engine weather layer, station selection and home commands, plus engine-to-browser selected-station events. Only the named commands are accepted.
- A Python setup script to generate the Unreal material and map assets using the actual engine.

The scene uses a **flat geographic map** with 3D markers. It does not yet contain elevation terrain, terrain-driven particles, road conditions, road cameras, thermals, or the full v3 feature set. No simulated terrain or synthetic weather is presented as real data.

**Verification boundary:** the engine and a compatible streaming GPU are absent from this web server. The Unreal source has not been compiled, packaged or executed. Actual rendering, engine API compatibility, encoding, gesture behavior and end-to-end streaming require validation on the Unreal host. Browser checks do not establish that Unreal streaming works.

## Build the Unreal application

On a Windows or Linux development machine with Unreal Engine 5.7, its C++ toolchain, and a supported GPU:

1. Copy `unreal/` to the machine. Generate project files from `SeifurV4.uproject` and compile the **Development Editor** target. Accept rebuilding the project module if prompted. Enable the original Pixel Streaming plugin, Procedural Mesh Component, Python Editor Script and Editor Scripting Utilities. Keep Pixel Streaming 2 disabled.
2. Run the setup script in the compiled editor (replace both paths with absolute paths):

   ```sh
   UnrealEditor-Cmd /path/SeifurV4.uproject -ExecutePythonScript=/path/bootstrap.py -Unattended -NoSplash
   ```

   The script creates `/Game/Materials/M_Weather` and `/Game/Maps/Iceland`. Initial startup can log a missing generated material before the script creates it. Exit and restart the editor after setup; generated `.uasset` and `.umap` files must exist before cooking.
3. Open `/Game/Maps/Iceland`, press Play and confirm the outline, markers, layers, HTTP refresh and camera behavior. `DefaultGame.ini` contains the read-only station URL and refresh interval. No API key is required.
4. Package for the GPU host OS, including the map, generated material and `Content/Data/iceland.json`. Example Linux packaging, with an appropriate installed/source engine and Linux toolchain:

   ```sh
   /path/UE/Engine/Build/BatchFiles/RunUAT.sh BuildCookRun \
     -project=/path/SeifurV4.uproject -noP4 -platform=Linux \
     -clientconfig=Shipping -build -cook -stage -pak -archive \
     -archivedirectory=/path/SeifurBuild
   ```

   Use `RunUAT.bat` and `-platform=Win64` on Windows. Run the packaged app locally before enabling streaming.

## Hosting needed for desktop and phones

The existing Plesk web server can continue to serve `/v4/` and the PHP weather APIs. It is not currently equipped to build or render Unreal. Pixel Streaming runs the engine on a separate GPU machine; the phone receives an interactive WebRTC video stream. The engine does not execute locally on the phone.

Required components:

1. **Unreal build machine:** Unreal 5.7, a matching C++ toolchain, enough disk space for the engine and cooked assets, and access under Epic's applicable license. Build on the workstation or GPU host, rather than this web server.
2. **GPU runtime host:** a supported OS, graphics drivers, Vulkan/D3D support as appropriate, and a compatible encoder such as NVIDIA NVENC or AMD AMF. H.264 is used for broad mobile browser compatibility. CPU, RAM, VRAM and bandwidth must be sized after measuring the packaged application and expected concurrent sessions. No paid host has been provisioned.
3. **Matching Epic signalling infrastructure:** clone the **UE5.7** branch on the GPU machine:

   ```sh
   git clone --branch UE5.7 --single-branch https://github.com/EpicGamesExt/PixelStreamingInfrastructure.git
   cd PixelStreamingInfrastructure
   ./SignallingWebServer/platform_scripts/bash/start.sh --httpPort 8080
   ```

   On Windows use the corresponding `platform_scripts/cmd/start.bat`. Confirm the actual listeners and options against this branch's README. The default engine signalling port is 8888; the sample player-facing reverse proxy assumes port 8080.
4. **TLS and DNS:** choose a streaming subdomain, terminate HTTPS/WSS there, and proxy WebSocket upgrades to the player signalling listener. `ops/nginx-stream.example.conf` is a template; it is not installed. Keep the engine signalling port private when the engine and signalling server share a machine. The reverse proxy carries signalling; WebRTC media uses the negotiated network routes.
5. **STUN and TURN:** configure reachable ICE services in the signalling server. TURN is needed for reliable cellular and restrictive-network access. Configure its TLS/UDP listeners, relay port range and firewall rules together. Supply short-lived TURN credentials through the signalling service; never put a shared TURN password or GPU-host secret in this public website's config. Test an actual iPhone on Safari and Android on Chrome using both Wi-Fi and cellular.
6. **Run the packaged engine:** use `ops/launch-unreal.sh` on a Linux GPU host, setting `SEIFUR_BINARY` to the real packaged executable. Its default engine signalling URL is `ws://127.0.0.1:8888` (local machine only). Supervise the engine and signalling services on the host.
7. **Connect v4:** set `signallingUrl` in `v4/config.json` to the public **`wss://` player-signalling endpoint**, not a webpage URL and not the private engine port. For example `wss://stream.example.com/`. Keep other API settings unchanged. Reload `/v4/`, select “Tengjast Unreal”, and verify real frames, layer changes, exact station details and station picking. If autoplay is blocked, use “Spila myndstreymi”. A failed connection returns to the overview.

One engine instance has one shared world and camera: connected viewers can affect each other's selection and view. Independent visitor sessions require a separate engine process per session and a session allocator, capacity limits and idle shutdown. These are not implemented in this initial project. Test one controlled session before opening a shared stream publicly.

## Browser development and verification

From `v4/`, using Node 24:

```sh
npm ci
npm run build
npm test
```

Verified here: browser build; four data/configuration unit checks; desktop and iPhone-sized Chromium checks with live station selection; unavailable-stream fallback; unavailable-data handling; Python and shell syntax checks. This is phone viewport emulation, not physical Safari or Android hardware testing.

Only `assets/player.js`, `styles.css`, `index.html`, `config.json` and the outline asset are required to serve the page. No CDN JavaScript or root dependency changes are needed. The browser smoke check is `node tests/browser.cjs` and uses the workspace's existing Playwright installation. Override `SEIFUR_V4_URL` for a staging server. Some hosts require their existing browser-library directory in `LD_LIBRARY_PATH`.

Before enabling a stream, verify GPU encoding, map/material cooking, stream reconnect, mobile video playback, real touch input, TURN relay on cellular networks, data freshness during an API outage, and session isolation as required for the intended audience.

References: [Epic Pixel Streaming](https://dev.epicgames.com/documentation/unreal-engine/pixel-streaming-in-unreal-engine), [supported hardware and browsers](https://dev.epicgames.com/documentation/unreal-engine/unreal-engine-pixel-streaming-reference), [hosting and networking](https://dev.epicgames.com/documentation/en-us/unreal-engine/hosting-and-networking-guide-for-pixel-streaming-in-unreal-engine), [official infrastructure](https://github.com/EpicGamesExt/PixelStreamingInfrastructure). Third-party attribution is in `THIRD_PARTY.md`.
