GTA 3 OPFS Cache Explained: Why the Browser Downloads Once

Origin Private File System is the key technology that lets GTA III Browser avoid downloading the same large archive on every visit. It gives the website a private, origin-scoped file area that JavaScript and workers can access without exposing a normal user-visible folder path.

What OPFS stores in this project

The persistent cache stores the compressed authorized GTA III ZIP as a browser-managed file plus small metadata describing whether the download completed, its size and source. The archive is not embedded in the website repository.

When you return, the launcher checks the cache metadata and file size before deciding whether it can reuse the local archive.

Why OPFS is better than downloading to RAM

A large archive held only in JavaScript memory would disappear on refresh and increase memory pressure during the entire transfer. Streaming the download to OPFS lets the worker write chunks as they arrive and retain the completed file for later sessions.

This is especially useful on slow connections because a successful first download becomes a local asset for the same site origin.

Background worker download flow

The OPFS cache worker performs the network transfer away from the main UI thread. It reports loaded and total bytes to the full-screen loader so the page can update progress without doing the file write work in the same event loop as the interface.

If the server advertises content length, the loader can show a meaningful percentage. If the total size is unknown, it can still display bytes written and an indeterminate progress state.

Range requests and resume behavior

The worker can attempt a range request for an interrupted remote download. When the upstream/proxy honors Range and returns HTTP 206, the worker seeks to the existing file offset and appends the remaining bytes.

If the server ignores range requests, the safe fallback is to restart the download rather than combine incompatible content. Resume therefore depends on both browser storage and server behavior.

Network data can be written once to OPFS and reused, while the active runtime still needs local extraction.

Why a Cloudflare proxy is used

Browser JavaScript must obey CORS. A file host can allow a top-level navigation download but still refuse a cross-origin fetch() from GitHub Pages. The proxy performs the upstream request server-side and returns headers that the browser worker can consume.

The proxy also forwards or reconstructs range-friendly headers so the downloader has a better chance of resuming large transfers.

Why the cached ZIP is still extracted each session

The current re3 WebAssembly build reads its game data from Emscripten's virtual filesystem. OPFS persistence does not automatically make every native-style file path visible inside that filesystem. The launcher therefore opens the cached ZIP and extracts relevant files into MEMFS for the active session.

This is a deliberate intermediate architecture: it saves network bandwidth while preserving the engine's expected filesystem layout.

When the cache disappears

Clearing site data, changing browser profiles, switching to a different origin or using some private-browsing modes can remove or isolate OPFS content. Browser storage policies can also evict data under extreme device storage pressure.

The launcher requests persistence where available, but the browser ultimately controls quota and storage lifecycle.

When you should clear the cache

Clear it when validation proves required files are missing, the archive is corrupted, the upstream archive was intentionally replaced or repeated extraction fails at a known bad point. Do not clear a valid cache to solve unrelated WebGL, input or FPS issues.