# Seifur v4 — Unreal 5.9 Preview browser target

Prepared 17 November 2026.

Entry page: https://seifur.vedrid.is/v4/web/

[Download the 5.9 web source package](assets/seifur-v4-ue59-web-source.tar.gz) (engine, SDK and compiled game excluded).

**Current status: source and browser integration prepared; Unreal has not been compiled or run.** There is no `.wasm` game installed. The entry page deliberately disables launch until an actual compiled stage is installed. Its WebGPU check is a capability check, not an Unreal rendering test.

## What changed

`unreal-web/` is a separate copy of the initial native scene, targeting engine 5.9. The existing `unreal/` 5.7 Pixel Streaming project, `/v4/` overview, and root production app remain available.

The web project removes the Pixel Streaming plugin, runtime component and build dependency. It keeps the geographically positioned flat Iceland map, measured station markers, wind-direction arrows, live observation refresh, mouse orbit, WASD pan, scroll and pinch zoom, and station picking. The unlit scene disables expensive rendering features for the initial mobile-renderer target. This remains a starter scene: elevation terrain, particles and the full v3 road layers are not implemented.

`BrowserBridge.h` uses Emscripten `EM_JS` functions to receive bounded browser commands on a game-thread timer and emit JSON events. It does not assume that Epic's generated page exports a particular `Module`, `ccall`, or Unreal private function. Emscripten helper dependencies are declared explicitly. The first milestone assumes the preview's default **single-thread mode**; thread proxying must be revisited before enabling multithreading.

The page hosts the **generated Unreal HTML page**, delivered through a small PHP response-header wrapper, in a same-origin iframe and provides layer and reset controls. It only enables these controls after the native scene sends its ready event. Message handling validates the origin, source window, channel and command. Closing the frame releases that runtime instance. The compiled game runs on the visitor's device; it does not require StreamPixel or a streaming GPU server.

## Why no compiled game exists yet

This machine has 8 GB RAM, about 28 GB free disk, no Unreal installation, and no Emscripten/compiler toolchain configured. Unreal source is not exposed through the connected GitHub installation. Installing only Emscripten cannot compile an Unreal project without the engine source, its platform tools and generated assets.

A separate build machine is needed. Epic recommends 32 GB RAM for its Linux editor, along with a supported GPU and graphics driver. Allow substantial additional storage for the engine checkout, dependencies, intermediate builds, shaders and cooked output; the available disk on this production web server is not a suitable build workspace. The current task is preparation here, as requested; no external machine or paid service has been provisioned.

## Build on a source-build machine

1. Obtain the intended Unreal **5.9 Preview** source through Epic's authorized download/GitHub access. The preview announcement links tag `5.9.0-preview-1`. Build the engine and its editor using that checkout's instructions. A 5.7 installed engine cannot produce this target.
2. Read **`Engine/Platforms/Wasm/README.md` from that exact checkout**. Set up its specified Emscripten SDK and supported host toolchain. We could verify the public preview announcement, release notes and known issues; we could not inspect the access-controlled platform README here. Do not substitute an arbitrary SDK version or assume the generic UAT invocation below matches every preview revision.
3. Copy `v4/unreal-web/`, `v4/ops/` and this guide to the build machine, preserving their relative layout. From the parent of `v4`, run a path/version preflight:

   ```sh
   python3 v4/ops/build_web.py --engine /path/to/UnrealEngine --phase check
   ```

   On Windows use `python` and the appropriate path. The helper supports Windows and Linux. This preflight checks engine paths, Build.version and the Wasm README; it does not certify the SDK or compile compatibility.
4. Build the project editor module, then generate the real material and map assets:

   ```sh
   python3 v4/ops/build_web.py --engine /path/to/UnrealEngine --phase editor
   python3 v4/ops/build_web.py --engine /path/to/UnrealEngine --phase assets
   ```

   The bootstrap creates `/Game/Materials/M_Weather` and `/Game/Maps/Iceland`. Initial editor startup may report that the material does not exist before the script generates it. Restart the editor after bootstrap, open the map and verify it in Play. No placeholder `.uasset` files are provided.
5. In the preview's Wasm project settings, keep the default mobile rendering tiers and single-thread mode. Target Shipping first for phone memory use. This scene needs neither Nanite/Lumen nor an audio thread. Do not enable an experimental desktop rendering tier for the first mobile test.
6. After checking the exact source README's packaging switches, run:

   ```sh
   python3 v4/ops/build_web.py --engine /path/to/UnrealEngine \
     --phase package --output /path/to/SeifurWebBuild
   ```

   The helper invokes standard `BuildCookRun` with `-platform=Wasm`, Shipping, build/cook/stage/pak/archive and an ASTC cook. **This command is a prepared invocation, not a verified successful build.** Amend the Wasm-specific switches if required by the actual preview checkout. Consult the source README for texture-set packaging; Epic's known-issues instructions mention `-cookflavor=ASTC` together with `-WasmAddTextureSet` when adding a phone-compatible texture set. A BC/DXT-only build is insufficient for many phones. Don't claim ASTC was included until the cook output and actual phone startup confirm it.
7. Run the generated page using the preview's supplied local web-serving tools, never `file://`. Test real rendering, the `ready` handshake, weather HTTP refresh, scene controls and browser messages. If packaging or startup fails, retain the build log and exact engine commit for diagnosis.

## Install an actual build on this website

Transfer the packaged web stage to a separate local directory on this host. Select the directory containing the generated `index.html`, its loader, `.wasm` and cooked content. Keep the generated layout intact.

Inspect first:

```sh
python3 v4/ops/install_web_build.py /path/to/packaged/Wasm
```

Install a trusted build:

```sh
python3 v4/ops/install_web_build.py /path/to/packaged/Wasm --install
```

The importer checks the index, loader, WebAssembly magic/version, nonempty cooked content and symlinks. It hashes files, checks disk space, copies to `web/runtime/`, adds a `seifur-entry.php` response-header wrapper which serves the original `index.html`, and then atomically updates `web/build.json`. It refuses to overwrite an existing runtime. It requires uncompressed `.wasm` so the HTTP MIME and magic can be checked; include uncompressed artifacts even when you also provide `.br` variants. Structural checks cannot prove that the stage is a valid Unreal build or will render; browser QA is still necessary. The manifest records `engineExecutionVerified: false`.

Hosting:

- HTTPS and correct `application/wasm` MIME type are required. JavaScript must retain a JavaScript MIME type.
- `web/index.php` delivers the entry page with COOP/COEP/CORP headers. The importer generates the equivalent `seifur-entry.php` wrapper for the compiled iframe. PHP is used because browser testing showed that some static responses bypass Apache rules. The live PHP entry was checked in Chromium. `web/.htaccess` supplies additional scoped header and MIME rules where Apache handles static files. Recheck the actual compiled iframe, `.wasm` MIME and browser isolation after installation.
- `ops/web/nginx.example.conf` is an optional location fragment if the host needs Nginx-level static-file configuration; preserve the existing PHP-FPM request handler. It has not been installed in the system configuration. It does not change production's response headers.
- Precompressed `.br` responses need `Content-Encoding: br` plus the underlying MIME type. Do not merely rename files. Start with the uncompressed files unless the generated loader and server agree on compression.
- The weather API is on the same origin, outside `/v4/web/`; no credentials are put in the browser or source package. Confirm browser HTTP requests in a real Wasm build, since the engine's platform HTTP implementation remains untested here.

## Verification completed here

- JavaScript data/configuration tests and extracted Emscripten bridge-body tests (origin/source/channel checks, bounded queue, allowed commands and emitted events).
- Python artifact inspection tests covering invalid/missing artifacts and symlinks.
- Desktop and iPhone-sized Chromium checks of the not-built page, responsive layout and isolation headers.
- A **simulated** iframe ready/command/stop test, plus rejection of an unsafe manifest entry. It is a protocol fixture, not Unreal execution.
- Python source syntax and the missing-engine preflight behavior.

Run these from the repository root:

```sh
npm test --prefix v4
PYTHONDONTWRITEBYTECODE=1 python3 v4/tests/web-package.test.py
node v4/tests/web-browser.cjs
```

Use the host's existing browser-library path in `LD_LIBRARY_PATH` if required. Native C++, shader compilation, cooking, WebAssembly execution, actual WebGPU rendering, performance and physical phones remain unverified.

## Phone validation after the first build

Start with Chrome desktop and an Android Chrome device, then physical iPhone Safari. Browser WebGPU support alone does not guarantee this preview fits the device's memory or texture support. Epic currently lists mobile startup, memory, texture, orientation and iOS issues. Keep single-thread mode, use compatible texture sets and test Shipping. The host appends `?audiothread=0` on iOS as a documented preview workaround. Confirm in the generated loader that this applies when loading the PHP entry wrapper; generated-page integration is still untested with a real build. Keep the phone orientation stable during startup and test rotation after loading.

## Primary references

- [Epic 5.9 Preview announcement and known issues](https://forums.unrealengine.com/t/unreal-engine-5-9-megajam-preview/2852840)
- [Epic 5.9 release notes](https://dev.epicgames.com/documentation/unreal-engine/unreal-engine-5-9-release-notes)
- [Epic Linux development requirements](https://dev.epicgames.com/documentation/en-us/unreal-engine/linux-development-quickstart-for-unreal-engine)
- [Emscripten EM_JS](https://emscripten.org/docs/api_reference/emscripten.h.html)
- [Emscripten JS helper dependency declarations](https://github.com/emscripten-core/emscripten/blob/main/system/include/emscripten/em_macros.h)
