From 05e2bc9f0a989f6023e659e12dd09d3d2a98b58e Mon Sep 17 00:00:00 2001
From: scamiv <6170744+scamiv@users.noreply.github.com>
Date: Mon, 23 Mar 2026 19:36:52 +0100
Subject: [PATCH] Improve cacheability with content-hashed public assets and a
 cacheable app shell (#3494)

## Description:

This reworks asset delivery and cacheability across the app and moves
non-bundled public resources onto immutable, content-hashed URLs.

Vite bundle outputs continue to live under `/assets/**` and remain
content-hashed by Vite. Public resources that were previously fetched
from stable paths in `resources/` now go through a custom hashed
namespace under `/_assets/**`, backed by a generated asset manifest that
is available to the server, browser, and worker runtime.

In parallel, the root app shell is now cacheable shared HTML instead of
request-time `no-store` HTML. Dynamic and live routes remain explicitly
uncached.

## Why
- Improve browser and Cloudflare cacheability for static assets.
- Remove query-string and release-version cache busting for
runtime-fetched assets.
- Allow unchanged public assets to keep the same URL across releases.
- Reduce avoidable work on `/` by serving a shared app shell instead of
rendering HTML on every request.
- Make cache behavior explicit instead of relying on mixed framework
defaults and file-extension heuristics.

## What Changed

### 1. Content-hashed public asset pipeline
- Added a build-time public asset manifest and hashing pipeline for
non-Vite resources.
- Production now emits hashed public assets under `/_assets/**`.
- Added runtime manifest loading for Node so server-rendered paths
resolve against built hashed files instead of rebuilding from source at
runtime.
- Emitted the runtime asset manifest as an ESM module for server
consumption.

Result:
- `/assets/**` = Vite-managed hashed bundle outputs
- `/_assets/**` = custom content-hashed public resources

### 2. Runtime asset URL migration
- Added a shared `assetUrl(...)` resolution path.
- Migrated runtime references away from query-string versioning and
stable source paths.
- Updated browser, worker, and server-side rendering paths to resolve
through the asset manifest.
- Moved map manifests, map binaries, thumbnails, sprites, sounds, fonts,
flags, icons, screenshots, and other runtime-fetched resources onto
hashed URLs.

### 3. Map and preview fixes
- Fixed directory and per-file map asset resolution so map manifest and
binary fetches resolve to the correct hashed URLs.
- Updated preview metadata and map thumbnail paths to use the hashed
asset namespace.
- Fixed runtime manifest loading in prod after deployment.

### 4. Explicit cache policies
- Added explicit immutable cache headers for:
  - `/assets/**`
  - `/_assets/**`
  - worker-prefixed equivalents under `/wN/...`
- Added explicit `no-store` headers for live and dynamic APIs.
- Removed the old `/api/env` bootstrap request and baked `gameEnv` into
the HTML bootstrap instead.

### 5. Cacheable root app shell
- Refactored the root HTML path to serve a shared app shell with:
- `Cache-Control: public, max-age=0, s-maxage=300,
stale-while-revalidate=86400`
- `/` and the SPA fallback now serve shared cacheable HTML instead of
request-time `no-store` rendering.
- `/game/:id` remains dynamic and `no-store`, but now reuses the shared
shell before injecting preview tags.

### 6. Matchmaking instance handling
- Because the app shell is now cacheable, `INSTANCE_ID` was removed from
shared HTML.
- Added `/api/instance` as a temporary `no-store` runtime lookup used
only by matchmaking.
- This preserves correctness with the current random-per-boot
`INSTANCE_ID` model while keeping `/` cacheable, but it is not the
intended long-term design.

## Behavior Changes

### Asset URL contract
Production URLs for non-Vite public resources now change from stable
paths such as:
- `/maps/...`
- `/images/...`
- `/manifest.json`

to content-hashed paths under:
- `/_assets/...`

Examples:
- `/_assets/maps/<map>/manifest.<hash>.json`
- `/_assets/images/Favicon.<hash>.svg`

### Bootstrap/config
- `/api/env` is removed.
- `gameEnv` is now bootstrapped from HTML.

### HTML caching
- `/` and the SPA fallback are now cacheable shared HTML.
- `/game/:id` remains dynamic.

## Cache Matrix After This Branch
- `/_assets/**`: `public, max-age=31536000, immutable`
- `/assets/**`: `public, max-age=31536000, immutable`
- live `/api/**`: explicit `no-store`
- `/api/health`: explicit `no-store`
- `/api/instance`: explicit `no-store`
- `/game/:id`: explicit `no-store`
- `/` and SPA fallback: `public, max-age=0, s-maxage=300,
stale-while-revalidate=86400`

## Notes / Tradeoffs
- `/api/instance` is a temporary compromise. It exists because
`INSTANCE_ID` is currently random per boot, which is not safe to embed
into cacheable shared HTML.
- The current matchmaking flow still asks the client to provide
`instance_id` during `matchmaking/join`. That is functional, but it is
the wrong ownership boundary: instance selection should be handled by
the matchmaking service, not by the browser.
- The cleaner end-state would be:
- make `matchmaking/join` stop requiring `instance_id` from the client,
and let the matchmaking service select a healthy instance from worker
check-ins
- This branch makes the origin behavior edge-cache-friendly, but
Cloudflare still needs matching cache rules if HTML itself should be
cached at the edge.

## Validation
Verified during development with:
- `npx tsc --noEmit`
- `node node_modules\\vite\\bin\\vite.js build`
- `node node_modules\\vitest\\vitest.mjs run
tests/server/RenderHtml.test.ts tests/server/NoStoreHeaders.test.ts
tests/server/StaticAssetCache.test.ts
tests/core/configuration/ConfigLoader.test.ts`

Additional targeted tests added:
- `tests/AssetUrls.test.ts`
- `tests/core/game/FetchGameMapLoader.test.ts`
- `tests/core/configuration/ConfigLoader.test.ts`
- `tests/server/NoStoreHeaders.test.ts`
- `tests/server/StaticAssetCache.test.ts`
- `tests/server/RenderHtml.test.ts`

## Known Existing Warnings
The production build still reports pre-existing warnings that are not
addressed by this branch:
- inconsistent JSON import attributes for `resources/countries.json`
- inconsistent JSON import attributes for `resources/QuickChat.json`
- large chunk warnings from Vite

## Rollout Notes
- Cache rules should treat `/_assets/**` and `/assets/**` as immutable.
- Cloudflare will still classify HTML as dynamic after deploy unless
matching edge cache rules are configured for it.

## Follow-ups
- Remove `/api/instance` by changing `matchmaking/join` so the server
selects the target instance, or by making `INSTANCE_ID` deploy-stable if
the current contract must remain.


## Please complete the following:

- [ ] I have added screenshots for all UI updates
- [ ] I process any text displayed to the user through translateText()
and I've added it to the en.json file
- [ ] I have added relevant tests to the test directory
- [ ] I confirm I have thoroughly tested these changes and take full
responsibility for any bugs introduced

## Please put your Discord username so you can be contacted if a bug or
regression is found:

DISCORD_USERNAME
---
 index.html                                    |  40 ++--
 nginx.conf                                    | 126 +++++++++---
 src/client/AccountModal.ts                    |   3 +-
 src/client/FlagInput.ts                       |  10 +-
 src/client/FlagInputModal.ts                  |   5 +-
 src/client/HelpModal.ts                       |  81 ++++----
 src/client/JoinLobbyModal.ts                  |   5 +-
 src/client/LangSelector.ts                    |   7 +-
 src/client/LanguageModal.ts                   |   3 +-
 src/client/Main.ts                            |   1 -
 src/client/Matchmaking.ts                     |  30 ++-
 src/client/NewsModal.ts                       |   7 +-
 src/client/SinglePlayerModal.ts               |   3 +-
 src/client/TerrainMapFileLoader.ts            |   6 +-
 src/client/TroubleshootingModal.ts            |   3 +-
 src/client/components/Footer.ts               |   5 +-
 .../baseComponents/ranking/PlayerRow.ts       |  17 +-
 src/client/components/map/MapDisplay.ts       |   4 +-
 src/client/components/map/MapPicker.ts        |   3 +-
 src/client/graphics/PlayerIcons.ts            |  31 +--
 src/client/graphics/SpriteLoader.ts           |  21 +-
 .../graphics/layers/AttackingTroopsOverlay.ts |   5 +-
 src/client/graphics/layers/AttacksDisplay.ts  |   5 +-
 src/client/graphics/layers/BuildMenu.ts       |  23 +--
 src/client/graphics/layers/ControlPanel.ts    |   7 +-
 src/client/graphics/layers/EventsDisplay.ts   |  11 +-
 src/client/graphics/layers/GameLeftSidebar.ts |  11 +-
 .../graphics/layers/GameRightSidebar.ts       |  11 +-
 src/client/graphics/layers/MainRadialMenu.ts  |   5 +-
 src/client/graphics/layers/NameLayer.ts       |   3 +-
 .../graphics/layers/PlayerInfoOverlay.ts      |  21 +-
 .../graphics/layers/PlayerModerationModal.ts  |   5 +-
 src/client/graphics/layers/PlayerPanel.ts     |  25 +--
 src/client/graphics/layers/RadialMenu.ts      |   3 +-
 .../graphics/layers/RadialMenuElements.ts     |  25 +--
 src/client/graphics/layers/SettingsModal.ts   |  27 +--
 .../graphics/layers/StructureDrawingUtils.ts  |  13 +-
 .../graphics/layers/StructureIconsLayer.ts    |   3 +-
 src/client/graphics/layers/StructureLayer.ts  |  13 +-
 src/client/graphics/layers/UnitDisplay.ts     |  23 +--
 src/client/sound/SoundManager.ts              |   3 +-
 src/client/vite-env.d.ts                      |  10 -
 src/core/AssetUrls.ts                         |  86 ++++++++
 src/core/CustomFlag.ts                        |   3 +-
 src/core/configuration/ConfigLoader.ts        |  25 ++-
 src/core/game/BinaryLoaderGameMapLoader.ts    |  15 +-
 src/core/game/FetchGameMapLoader.ts           |  18 +-
 src/core/worker/Worker.worker.ts              |   5 +-
 src/server/GamePreviewBuilder.ts              |  16 +-
 src/server/GamePreviewRoute.ts                |   8 +-
 src/server/Master.ts                          |  47 ++---
 src/server/NoStoreHeaders.ts                  |  10 +
 src/server/PublicAssetManifest.ts             | 187 ++++++++++++++++++
 src/server/RenderHtml.ts                      |  55 +++++-
 src/server/RuntimeAssetManifest.ts            |  40 ++++
 src/server/StaticAssetCache.ts                |  33 ++++
 src/server/Worker.ts                          |  18 +-
 tests/AssetUrls.test.ts                       |  46 +++++
 tests/core/configuration/ConfigLoader.test.ts |  24 +++
 tests/core/game/FetchGameMapLoader.test.ts    |  30 +++
 tests/server/NoStoreHeaders.test.ts           |  21 ++
 tests/server/PublicAssetManifest.test.ts      |  71 +++++++
 tests/server/RenderHtml.test.ts               |  60 ++++++
 tests/server/StaticAssetCache.test.ts         |  21 ++
 vite.config.ts                                |  43 +++-
 65 files changed, 1214 insertions(+), 331 deletions(-)
 create mode 100644 src/core/AssetUrls.ts
 create mode 100644 src/server/NoStoreHeaders.ts
 create mode 100644 src/server/PublicAssetManifest.ts
 create mode 100644 src/server/RuntimeAssetManifest.ts
 create mode 100644 src/server/StaticAssetCache.ts
 create mode 100644 tests/AssetUrls.test.ts
 create mode 100644 tests/core/configuration/ConfigLoader.test.ts
 create mode 100644 tests/core/game/FetchGameMapLoader.test.ts
 create mode 100644 tests/server/NoStoreHeaders.test.ts
 create mode 100644 tests/server/PublicAssetManifest.test.ts
 create mode 100644 tests/server/RenderHtml.test.ts
 create mode 100644 tests/server/StaticAssetCache.test.ts

diff --git a/index.html b/index.html
index 5db9deb74..ebb12432d 100644
--- a/index.html
+++ b/index.html
@@ -7,8 +7,8 @@
       content="width=device-width, initial-scale=1.0, viewport-fit=cover"
     />
     <title data-i18n="main.title">OpenFront (ALPHA)</title>
-    <link rel="manifest" href="/manifest.json" />
-    <link rel="icon" type="image/svg+xml" href="/images/Favicon.svg" />
+    <link rel="manifest" href="<%- manifestHref %>" />
+    <link rel="icon" type="image/svg+xml" href="<%- faviconHref %>" />
 
     <!-- Preload styles -->
     <style>
@@ -50,16 +50,28 @@
       property="og:description"
       content="Conquer the world in this multiplayer battle royale! Expand your nation, eliminate opponents, and dominate the map in this fast-paced IO game."
     />
-    <meta
-      property="og:image"
-      content="https://openfront.io/images/GameplayScreenshot.png"
-    />
+    <meta property="og:image" content="<%- gameplayScreenshotUrl %>" />
     <meta property="og:type" content="game" />
 
     <!-- Injected from Server env -->
     <script>
       window.GIT_COMMIT = <%- gitCommit %>;
-      window.INSTANCE_ID = <%- instanceId %>;
+      window.ASSET_MANIFEST = <%- assetManifest %>;
+      window.BOOTSTRAP_CONFIG = {
+        gameEnv: <%- gameEnv %>,
+      };
+      document.documentElement.style.setProperty(
+        "--background-image-url",
+        `url("<%- backgroundImageUrl %>")`,
+      );
+      document.documentElement.style.setProperty(
+        "--desktop-logo-image-url",
+        `url("<%- desktopLogoImageUrl %>")`,
+      );
+      document.documentElement.style.setProperty(
+        "--mobile-logo-image-url",
+        `url("<%- mobileLogoImageUrl %>")`,
+      );
     </script>
 
     <!-- CrazyGames SDK -->
@@ -126,23 +138,15 @@
       <div
         id="background-layer"
         class="absolute inset-0 bg-cover bg-center opacity-30 [filter:brightness(1.0)] dark:[filter:sepia(0.2)_saturate(1.2)_hue-rotate(180deg)_brightness(0.9)]"
-        style="
-          background-image: url(&quot;/resources/images/background.webp&quot;);
-        "
+        style="background-image: var(--background-image-url)"
       ></div>
       <div
         class="absolute inset-0 bg-center bg-no-repeat bg-contain hidden lg:block"
-        style="
-          background-image: url(&quot;/resources/images/OpenFront.webp&quot;);
-          opacity: 0.5;
-        "
+        style="background-image: var(--desktop-logo-image-url); opacity: 0.5"
       ></div>
       <div
         class="absolute inset-0 bg-center bg-no-repeat bg-contain lg:hidden"
-        style="
-          background-image: url(&quot;/resources/images/OF.webp&quot;);
-          opacity: 0.5;
-        "
+        style="background-image: var(--mobile-logo-image-url); opacity: 0.5"
       ></div>
     </div>
 
diff --git a/nginx.conf b/nginx.conf
index 8466fd86c..1465684f9 100644
--- a/nginx.conf
+++ b/nginx.conf
@@ -17,6 +17,99 @@ server {
     access_log /var/log/nginx/access.log;
     error_log /var/log/nginx/error.log;
 
+    location ^~ /assets/ {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_cache STATIC;
+        proxy_cache_valid 200 302 24h;
+        proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
+        proxy_cache_lock on;
+        add_header X-Cache-Status $upstream_cache_status;
+        add_header Cache-Control "public, max-age=31536000, immutable";
+
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    location ^~ /_assets/ {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_cache STATIC;
+        proxy_cache_valid 200 302 24h;
+        proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
+        proxy_cache_lock on;
+        add_header X-Cache-Status $upstream_cache_status;
+        add_header Cache-Control "public, max-age=31536000, immutable";
+
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    location ~* ^/w(\d+)(/(?:assets|_assets)/.*)$ {
+        set $worker $1;
+        set $worker_port 3001;
+
+        if ($worker = "0") { set $worker_port 3001; }
+        if ($worker = "1") { set $worker_port 3002; }
+        if ($worker = "2") { set $worker_port 3003; }
+        if ($worker = "3") { set $worker_port 3004; }
+        if ($worker = "4") { set $worker_port 3005; }
+        if ($worker = "5") { set $worker_port 3006; }
+        if ($worker = "6") { set $worker_port 3007; }
+        if ($worker = "7") { set $worker_port 3008; }
+        if ($worker = "8") { set $worker_port 3009; }
+        if ($worker = "9") { set $worker_port 3010; }
+        if ($worker = "10") { set $worker_port 3011; }
+        if ($worker = "11") { set $worker_port 3012; }
+        if ($worker = "12") { set $worker_port 3013; }
+        if ($worker = "13") { set $worker_port 3014; }
+        if ($worker = "14") { set $worker_port 3015; }
+        if ($worker = "15") { set $worker_port 3016; }
+        if ($worker = "16") { set $worker_port 3017; }
+        if ($worker = "17") { set $worker_port 3018; }
+        if ($worker = "18") { set $worker_port 3019; }
+        if ($worker = "19") { set $worker_port 3020; }
+        if ($worker = "20") { set $worker_port 3021; }
+        if ($worker = "21") { set $worker_port 3022; }
+        if ($worker = "22") { set $worker_port 3023; }
+        if ($worker = "23") { set $worker_port 3024; }
+        if ($worker = "24") { set $worker_port 3025; }
+        if ($worker = "25") { set $worker_port 3026; }
+        if ($worker = "26") { set $worker_port 3027; }
+        if ($worker = "27") { set $worker_port 3028; }
+        if ($worker = "28") { set $worker_port 3029; }
+        if ($worker = "29") { set $worker_port 3030; }
+        if ($worker = "30") { set $worker_port 3031; }
+        if ($worker = "31") { set $worker_port 3032; }
+        if ($worker = "32") { set $worker_port 3033; }
+        if ($worker = "33") { set $worker_port 3034; }
+        if ($worker = "34") { set $worker_port 3035; }
+        if ($worker = "35") { set $worker_port 3036; }
+        if ($worker = "36") { set $worker_port 3037; }
+        if ($worker = "37") { set $worker_port 3038; }
+        if ($worker = "38") { set $worker_port 3039; }
+        if ($worker = "39") { set $worker_port 3040; }
+        if ($worker = "40") { set $worker_port 3041; }
+
+        proxy_pass http://127.0.0.1:$worker_port$2$is_args$args;
+        proxy_cache STATIC;
+        proxy_cache_valid 200 302 24h;
+        proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
+        proxy_cache_lock on;
+        add_header X-Cache-Status $upstream_cache_status;
+        add_header Cache-Control "public, max-age=31536000, immutable";
+
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
     # Worker locations - Processing this first so worker-specific requests are handled by workers
     # This prevents static file regexes from capturing worker requests
     location ~* ^/w(\d+)(/.*)?$ {
@@ -102,25 +195,6 @@ server {
         add_header Cache-Control "public, max-age=86400";  # 24 hours
     }
     
-    # /api/env endpoint - Cache for 1 hour
-    location = /api/env {
-        proxy_pass http://127.0.0.1:3000;
-        proxy_http_version 1.1;
-        
-        # Cache configuration
-        proxy_cache API_CACHE;
-        proxy_cache_valid 200 1h;  # Cache successful responses for 1 hour
-        proxy_cache_use_stale error timeout http_500 http_502 http_503 http_504;
-        proxy_cache_lock on;
-        add_header X-Cache-Status $upstream_cache_status;
-        
-        # Standard proxy headers
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-
     # /api/health endpoint - No caching, always hit the backend
     location = /api/health {
         proxy_pass http://127.0.0.1:3000;
@@ -230,18 +304,14 @@ server {
     }
 
 
-    # Root location with short Nginx cache but no browser cache
+    # Root location with short shared cache for the app shell
     location = / {
         proxy_pass http://127.0.0.1:3000;
-        
-        # Tell browsers not to cache
-        add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate";
-        add_header Pragma "no-cache";
-        add_header Expires "0";
-        
-        # But let Nginx cache for 1 second to reduce load
+
+        # Cache the shared app shell briefly at the proxy; browser/CDN policy
+        # comes from the upstream Cache-Control header.
         proxy_cache STATIC;
-        proxy_cache_valid 200 302 1s;
+        proxy_cache_valid 200 302 300s;
         proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
         proxy_cache_lock on;
         
diff --git a/src/client/AccountModal.ts b/src/client/AccountModal.ts
index 0268d21d2..0536c0a58 100644
--- a/src/client/AccountModal.ts
+++ b/src/client/AccountModal.ts
@@ -5,6 +5,7 @@ import {
   PlayerStatsTree,
   UserMeResponse,
 } from "../core/ApiSchemas";
+import { assetUrl } from "../core/AssetUrls";
 import { getServerConfigFromClient } from "../core/configuration/ConfigLoader";
 import { fetchPlayerById, getUserMe } from "./Api";
 import { discordLogin, logOut, sendMagicLink } from "./Auth";
@@ -274,7 +275,7 @@ export class AccountModal extends BaseModal {
               class="w-full px-6 py-4 text-white bg-[#5865F2] hover:bg-[#4752C4] border border-transparent rounded-xl focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-[#5865F2] transition-colors duration-200 flex items-center justify-center gap-3 group relative overflow-hidden shadow-lg hover:shadow-[#5865F2]/20"
             >
               <img
-                src="/images/DiscordLogo.svg"
+                src=${assetUrl("images/DiscordLogo.svg")}
                 alt="Discord"
                 class="w-6 h-6 relative z-10"
               />
diff --git a/src/client/FlagInput.ts b/src/client/FlagInput.ts
index 0622937cf..d363f186e 100644
--- a/src/client/FlagInput.ts
+++ b/src/client/FlagInput.ts
@@ -1,5 +1,6 @@
 import { LitElement, html } from "lit";
 import { customElement, property, state } from "lit/decorators.js";
+import { assetUrl } from "../core/AssetUrls";
 import { renderPlayerFlag } from "../core/CustomFlag";
 import { FlagSchema } from "../core/Schemas";
 import { translateText } from "./Utils";
@@ -120,12 +121,15 @@ export class FlagInput extends LitElement {
       renderPlayerFlag(this.flag, preview);
     } else {
       const img = document.createElement("img");
-      img.src = this.flag ? `/flags/${this.flag}.svg` : `/flags/xx.svg`;
+      const fallbackFlagUrl = assetUrl("flags/xx.svg");
+      img.src = this.flag
+        ? assetUrl(`flags/${this.flag}.svg`)
+        : fallbackFlagUrl;
       img.className = "w-full h-full object-cover pointer-events-none";
       img.draggable = false;
       img.onerror = () => {
-        if (!img.src.endsWith("/flags/xx.svg")) {
-          img.src = "/flags/xx.svg";
+        if (!img.src.endsWith(fallbackFlagUrl)) {
+          img.src = fallbackFlagUrl;
         }
       };
       preview.appendChild(img);
diff --git a/src/client/FlagInputModal.ts b/src/client/FlagInputModal.ts
index 8451b4e5d..217d17da8 100644
--- a/src/client/FlagInputModal.ts
+++ b/src/client/FlagInputModal.ts
@@ -1,6 +1,7 @@
 import { html } from "lit";
 import { customElement, query, state } from "lit/decorators.js";
 import Countries from "resources/countries.json" with { type: "json" };
+import { assetUrl } from "../core/AssetUrls";
 import { translateText } from "./Utils";
 import { BaseModal } from "./components/BaseModal";
 import { modalHeader } from "./components/ui/ModalHeader";
@@ -61,11 +62,11 @@ export class FlagInputModal extends BaseModal {
                   <img
                     class="w-full h-auto rounded group-hover:scale-105 transition-transform duration-200 pointer-events-none"
                     draggable="false"
-                    src="/flags/${country.code}.svg"
+                    src=${assetUrl(`flags/${country.code}.svg`)}
                     loading="lazy"
                     @error=${(e: Event) => {
                       const img = e.currentTarget as HTMLImageElement;
-                      const fallback = "/flags/xx.svg";
+                      const fallback = assetUrl("flags/xx.svg");
                       if (img.src && !img.src.endsWith(fallback)) {
                         img.src = fallback;
                       }
diff --git a/src/client/HelpModal.ts b/src/client/HelpModal.ts
index b66336d9d..f791d13f1 100644
--- a/src/client/HelpModal.ts
+++ b/src/client/HelpModal.ts
@@ -1,6 +1,7 @@
 import { html } from "lit";
 import { customElement, query, state } from "lit/decorators.js";
 import { translateText, TUTORIAL_VIDEO_URL } from "../client/Utils";
+import { assetUrl } from "../core/AssetUrls";
 import { BaseModal } from "./components/BaseModal";
 import "./components/Difficulties";
 import { modalHeader } from "./components/ui/ModalHeader";
@@ -527,7 +528,7 @@ export class HelpModal extends BaseModal {
                     >${translateText("help_modal.ui_leaderboard")}</span
                   >
                   <img
-                    src="/images/helpModal/leaderboard2.webp"
+                    src=${assetUrl("images/helpModal/leaderboard2.webp")}
                     alt="Leaderboard"
                     class="rounded-lg shadow-lg border border-white/20 max-w-[200px]"
                     loading="lazy"
@@ -550,7 +551,7 @@ export class HelpModal extends BaseModal {
                     >${translateText("help_modal.ui_control")}</span
                   >
                   <img
-                    src="/images/helpModal/controlPanel.webp"
+                    src=${assetUrl("images/helpModal/controlPanel.webp")}
                     alt="Control Panel"
                     class="rounded-lg shadow-lg border border-white/20 max-w-[200px]"
                     loading="lazy"
@@ -578,13 +579,13 @@ export class HelpModal extends BaseModal {
                   >
                   <div class="flex flex-col gap-2">
                     <img
-                      src="/images/helpModal/eventsPanel.webp"
+                      src=${assetUrl("images/helpModal/eventsPanel.webp")}
                       alt="Events"
                       class="rounded-lg shadow-lg border border-white/20 max-w-[200px]"
                       loading="lazy"
                     />
                     <img
-                      src="/images/helpModal/eventsPanelAttack.webp"
+                      src=${assetUrl("images/helpModal/eventsPanelAttack.webp")}
                       alt="Events Attack"
                       class="rounded-lg shadow-lg border border-white/20 max-w-[200px]"
                       loading="lazy"
@@ -613,7 +614,7 @@ export class HelpModal extends BaseModal {
                     >${translateText("help_modal.ui_options")}</span
                   >
                   <img
-                    src="/images/helpModal/options2.webp"
+                    src=${assetUrl("images/helpModal/options2.webp")}
                     alt="Options"
                     class="rounded-lg shadow-lg border border-white/20 max-w-[200px]"
                     loading="lazy"
@@ -643,7 +644,7 @@ export class HelpModal extends BaseModal {
                     >${translateText("help_modal.ui_playeroverlay")}</span
                   >
                   <img
-                    src="/images/helpModal/playerInfoOverlay.webp"
+                    src=${assetUrl("images/helpModal/playerInfoOverlay.webp")}
                     alt="Player Info"
                     class="rounded-lg shadow-lg border border-white/20 max-w-[200px]"
                     loading="lazy"
@@ -692,13 +693,13 @@ export class HelpModal extends BaseModal {
             >
               <div class="flex flex-col gap-4 shrink-0">
                 <img
-                  src="/images/helpModal/radialMenu2.webp"
+                  src=${assetUrl("images/helpModal/radialMenu2.webp")}
                   alt="Radial Menu"
                   class="rounded-lg shadow-lg border border-white/20 max-w-[200px]"
                   loading="lazy"
                 />
                 <img
-                  src="/images/helpModal/radialMenuAlly.webp"
+                  src=${assetUrl("images/helpModal/radialMenuAlly.webp")}
                   alt="Radial Menu Ally"
                   class="rounded-lg shadow-lg border border-white/20 max-w-[200px]"
                   loading="lazy"
@@ -711,42 +712,42 @@ export class HelpModal extends BaseModal {
                 <ul class="space-y-3">
                   <li class="flex items-center gap-3">
                     <img
-                      src="/images/BuildIconWhite.svg"
+                      src=${assetUrl("images/BuildIconWhite.svg")}
                       class="w-8 h-8 scale-75 origin-left"
                     />
                     <span>${translateText("help_modal.radial_build")}</span>
                   </li>
                   <li class="flex items-center gap-3">
                     <img
-                      src="/images/InfoIcon.svg"
+                      src=${assetUrl("images/InfoIcon.svg")}
                       class="w-8 h-8 scale-75 origin-left"
                     />
                     <span>${translateText("help_modal.radial_info")}</span>
                   </li>
                   <li class="flex items-center gap-3">
                     <img
-                      src="/images/BoatIconWhite.svg"
+                      src=${assetUrl("images/BoatIconWhite.svg")}
                       class="w-8 h-8 scale-75 origin-left"
                     />
                     <span>${translateText("help_modal.radial_boat")}</span>
                   </li>
                   <li class="flex items-center gap-3">
                     <img
-                      src="/images/AllianceIconWhite.svg"
+                      src=${assetUrl("images/AllianceIconWhite.svg")}
                       class="w-8 h-8 scale-75 origin-left"
                     />
                     <span>${translateText("help_modal.info_alliance")}</span>
                   </li>
                   <li class="flex items-center gap-3">
                     <img
-                      src="/images/TraitorIconWhite.svg"
+                      src=${assetUrl("images/TraitorIconWhite.svg")}
                       class="w-8 h-8 scale-75 origin-left"
                     />
                     <span>${translateText("help_modal.ally_betray")}</span>
                   </li>
                   <li class="flex items-center gap-3">
                     <img
-                      src="/images/DonateTroopIconWhite.svg"
+                      src=${assetUrl("images/DonateTroopIconWhite.svg")}
                       class="w-8 h-8 scale-75 origin-left"
                     />
                     <span
@@ -755,7 +756,7 @@ export class HelpModal extends BaseModal {
                   </li>
                   <li class="flex items-center gap-3">
                     <img
-                      src="/images/DonateGoldIconWhite.svg"
+                      src=${assetUrl("images/DonateGoldIconWhite.svg")}
                       class="w-8 h-8 scale-75 origin-left"
                     />
                     <span
@@ -808,7 +809,7 @@ export class HelpModal extends BaseModal {
                     >${translateText("help_modal.info_enemy_panel")}</span
                   >
                   <img
-                    src="/images/helpModal/infoMenu2.webp"
+                    src=${assetUrl("images/helpModal/infoMenu2.webp")}
                     alt="Enemy Info"
                     class="rounded-lg shadow-lg border border-white/20 max-w-[240px]"
                     loading="lazy"
@@ -821,35 +822,35 @@ export class HelpModal extends BaseModal {
                   <ul class="space-y-3">
                     <li class="flex items-center gap-3">
                       <img
-                        src="/images/ChatIconWhite.svg"
+                        src=${assetUrl("images/ChatIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                       <span>${translateText("help_modal.info_chat")}</span>
                     </li>
                     <li class="flex items-center gap-3">
                       <img
-                        src="/images/TargetIconWhite.svg"
+                        src=${assetUrl("images/TargetIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                       <span>${translateText("help_modal.info_target")}</span>
                     </li>
                     <li class="flex items-center gap-3">
                       <img
-                        src="/images/AllianceIconWhite.svg"
+                        src=${assetUrl("images/AllianceIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                       <span>${translateText("help_modal.info_alliance")}</span>
                     </li>
                     <li class="flex items-center gap-3">
                       <img
-                        src="/images/EmojiIconWhite.svg"
+                        src=${assetUrl("images/EmojiIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                       <span>${translateText("help_modal.info_emoji")}</span>
                     </li>
                     <li class="flex items-center gap-3">
                       <img
-                        src="/images/StopIconWhite.png"
+                        src=${assetUrl("images/StopIconWhite.png")}
                         class="w-8 h-8 scale-75 origin-left"
                         loading="lazy"
                       />
@@ -869,7 +870,7 @@ export class HelpModal extends BaseModal {
                     >${translateText("help_modal.info_ally_panel")}</span
                   >
                   <img
-                    src="/images/helpModal/infoMenu2Ally.webp"
+                    src=${assetUrl("images/helpModal/infoMenu2Ally.webp")}
                     alt="Ally Info"
                     class="rounded-lg shadow-lg border border-white/20 max-w-[240px]"
                     loading="lazy"
@@ -882,21 +883,21 @@ export class HelpModal extends BaseModal {
                   <ul class="space-y-3">
                     <li class="flex items-center gap-3">
                       <img
-                        src="/images/TraitorIconWhite.svg"
+                        src=${assetUrl("images/TraitorIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                       <span>${translateText("help_modal.ally_betray")}</span>
                     </li>
                     <li class="flex items-center gap-3">
                       <img
-                        src="/images/DonateTroopIconWhite.svg"
+                        src=${assetUrl("images/DonateTroopIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                       <span>${translateText("help_modal.ally_donate")}</span>
                     </li>
                     <li class="flex items-center gap-3">
                       <img
-                        src="/images/DonateGoldIconWhite.svg"
+                        src=${assetUrl("images/DonateGoldIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                       <span
@@ -971,7 +972,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/CityIconWhite.svg"
+                        src=${assetUrl("images/CityIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -987,7 +988,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/ShieldIconWhite.svg"
+                        src=${assetUrl("images/ShieldIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -1003,7 +1004,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/PortIcon.svg"
+                        src=${assetUrl("images/PortIcon.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -1019,7 +1020,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/FactoryIconWhite.svg"
+                        src=${assetUrl("images/FactoryIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -1035,7 +1036,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/BattleshipIconWhite.svg"
+                        src=${assetUrl("images/BattleshipIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -1051,7 +1052,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/MissileSiloIconWhite.svg"
+                        src=${assetUrl("images/MissileSiloIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -1067,7 +1068,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/SamLauncherIconWhite.svg"
+                        src=${assetUrl("images/SamLauncherIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -1083,7 +1084,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/NukeIconWhite.svg"
+                        src=${assetUrl("images/NukeIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -1099,7 +1100,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/MushroomCloudIconWhite.svg"
+                        src=${assetUrl("images/MushroomCloudIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -1115,7 +1116,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/MIRVIcon.svg"
+                        src=${assetUrl("images/MIRVIcon.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -1169,7 +1170,7 @@ export class HelpModal extends BaseModal {
                 class="bg-black/20 rounded-xl border border-white/10 p-4 flex flex-col items-center gap-3 hover:bg-white/5 transition-colors"
               >
                 <img
-                  src="/images/helpModal/crown.webp"
+                  src=${assetUrl("images/helpModal/crown.webp")}
                   alt="Rank 1"
                   class="rounded shadow-lg border border-white/10 h-24 w-auto object-contain"
                   loading="lazy"
@@ -1186,7 +1187,7 @@ export class HelpModal extends BaseModal {
                 class="bg-black/20 rounded-xl border border-white/10 p-4 flex flex-col items-center gap-3 hover:bg-white/5 transition-colors"
               >
                 <img
-                  src="/images/helpModal/traitor2.webp"
+                  src=${assetUrl("images/helpModal/traitor2.webp")}
                   alt="Traitor"
                   class="rounded shadow-lg border border-white/10 h-24 w-auto object-contain"
                   loading="lazy"
@@ -1203,7 +1204,7 @@ export class HelpModal extends BaseModal {
                 class="bg-black/20 rounded-xl border border-white/10 p-4 flex flex-col items-center gap-3 hover:bg-white/5 transition-colors"
               >
                 <img
-                  src="/images/helpModal/ally2.webp"
+                  src=${assetUrl("images/helpModal/ally2.webp")}
                   alt="Ally"
                   class="rounded shadow-lg border border-white/10 h-24 w-auto object-contain"
                   loading="lazy"
@@ -1220,7 +1221,7 @@ export class HelpModal extends BaseModal {
                 class="bg-black/20 rounded-xl border border-white/10 p-4 flex flex-col items-center gap-3 hover:bg-white/5 transition-colors"
               >
                 <img
-                  src="/images/helpModal/embargo.webp"
+                  src=${assetUrl("images/helpModal/embargo.webp")}
                   alt="Embargo"
                   class="rounded shadow-lg border border-white/10 h-24 w-auto object-contain"
                   loading="lazy"
@@ -1237,7 +1238,7 @@ export class HelpModal extends BaseModal {
                 class="bg-black/20 rounded-xl border border-white/10 p-4 flex flex-col items-center gap-3 hover:bg-white/5 transition-colors"
               >
                 <img
-                  src="/images/helpModal/allianceRequest.webp"
+                  src=${assetUrl("images/helpModal/allianceRequest.webp")}
                   alt="Request"
                   class="rounded shadow-lg border border-white/10 h-24 w-auto object-contain"
                   loading="lazy"
diff --git a/src/client/JoinLobbyModal.ts b/src/client/JoinLobbyModal.ts
index 3d6ff86c9..38b41ec69 100644
--- a/src/client/JoinLobbyModal.ts
+++ b/src/client/JoinLobbyModal.ts
@@ -8,6 +8,7 @@ import {
   renderDuration,
   translateText,
 } from "../client/Utils";
+import { assetUrl } from "../core/AssetUrls";
 import { EventBus } from "../core/EventBus";
 import {
   ClientInfo,
@@ -431,7 +432,9 @@ export class JoinLobbyModal extends BaseModal {
     const c = this.gameConfig;
     const mapName = getMapName(c.gameMap);
     const normalizedMap = normaliseMapKey(c.gameMap);
-    const thumbnailUrl = `/maps/${encodeURIComponent(normalizedMap)}/thumbnail.webp`;
+    const thumbnailUrl = assetUrl(
+      `maps/${encodeURIComponent(normalizedMap)}/thumbnail.webp`,
+    );
     const isTeam = c.gameMode === GameMode.Team;
 
     let modeSubtitle: string;
diff --git a/src/client/LangSelector.ts b/src/client/LangSelector.ts
index 2ba0ee498..a373a73ce 100644
--- a/src/client/LangSelector.ts
+++ b/src/client/LangSelector.ts
@@ -1,5 +1,6 @@
 import { LitElement, html } from "lit";
 import { customElement, state } from "lit/decorators.js";
+import { assetUrl } from "../core/AssetUrls";
 import "./LanguageModal";
 import { LanguageModal } from "./LanguageModal";
 import { formatDebugTranslation } from "./Utils";
@@ -118,7 +119,9 @@ export class LangSelector extends LitElement {
     }
 
     try {
-      const response = await fetch(`/lang/${encodeURIComponent(lang)}.json`);
+      const response = await fetch(
+        assetUrl(`lang/${encodeURIComponent(lang)}.json`),
+      );
       if (!response.ok) {
         throw new Error(`Failed to fetch language ${lang}: ${response.status}`);
       }
@@ -354,7 +357,7 @@ export class LangSelector extends LitElement {
         <img
           id="lang-flag"
           class="object-contain pointer-events-none transition-all w-[40px] h-[40px] lg:w-[48px] lg:h-[48px]"
-          src="/flags/${currentLang.svg}.svg"
+          src=${assetUrl(`flags/${currentLang.svg}.svg`)}
           alt="flag"
           draggable="false"
         />
diff --git a/src/client/LanguageModal.ts b/src/client/LanguageModal.ts
index 7e6023648..4fd2651e4 100644
--- a/src/client/LanguageModal.ts
+++ b/src/client/LanguageModal.ts
@@ -1,6 +1,7 @@
 import { html } from "lit";
 import { customElement, property } from "lit/decorators.js";
 import { translateText } from "../client/Utils";
+import { assetUrl } from "../core/AssetUrls";
 import "./components/baseComponents/Modal";
 import { BaseModal } from "./components/BaseModal";
 import { modalHeader } from "./components/ui/ModalHeader";
@@ -69,7 +70,7 @@ export class LanguageModal extends BaseModal {
                   @click=${() => this.selectLanguage(lang.code)}
                 >
                   <img
-                    src="/flags/${lang.svg}.svg"
+                    src=${assetUrl(`flags/${lang.svg}.svg`)}
                     class="w-8 h-6 object-contain rounded-sm shrink-0"
                     alt="${lang.code}"
                   />
diff --git a/src/client/Main.ts b/src/client/Main.ts
index 59c70c044..b4ed449af 100644
--- a/src/client/Main.ts
+++ b/src/client/Main.ts
@@ -169,7 +169,6 @@ function updateAccountNavButton(userMeResponse: UserMeResponse | false) {
 declare global {
   interface Window {
     GIT_COMMIT: string;
-    INSTANCE_ID: string;
     turnstile: any;
     adsEnabled: boolean;
     PageOS: {
diff --git a/src/client/Matchmaking.ts b/src/client/Matchmaking.ts
index 735f56141..79ddc3da9 100644
--- a/src/client/Matchmaking.ts
+++ b/src/client/Matchmaking.ts
@@ -13,6 +13,7 @@ import { translateText } from "./Utils";
 
 @customElement("matchmaking-modal")
 export class MatchmakingModal extends BaseModal {
+  private static instanceIdPromise: Promise<string> | null = null;
   private gameCheckInterval: ReturnType<typeof setInterval> | null = null;
   private connectTimeout: ReturnType<typeof setTimeout> | null = null;
   @state() private connected = false;
@@ -87,9 +88,10 @@ export class MatchmakingModal extends BaseModal {
 
   private async connect() {
     const config = await getServerConfigFromClient();
+    const instanceId = await MatchmakingModal.getInstanceId();
 
     this.socket = new WebSocket(
-      `${config.jwtIssuer()}/matchmaking/join?instance_id=${window.INSTANCE_ID}`,
+      `${config.jwtIssuer()}/matchmaking/join?instance_id=${encodeURIComponent(instanceId)}`,
     );
     this.socket.onopen = async () => {
       console.log("Connected to matchmaking server");
@@ -130,6 +132,32 @@ export class MatchmakingModal extends BaseModal {
     };
   }
 
+  private static async getInstanceId(): Promise<string> {
+    MatchmakingModal.instanceIdPromise ??= fetch("/api/instance", {
+      cache: "no-store",
+    })
+      .then(async (response) => {
+        if (!response.ok) {
+          throw new Error(
+            `Failed to load instance id: ${response.status} ${response.statusText}`,
+          );
+        }
+
+        const data = (await response.json()) as { instanceId?: string };
+        if (!data.instanceId) {
+          throw new Error("Missing instance id");
+        }
+
+        return data.instanceId;
+      })
+      .catch((error: unknown) => {
+        MatchmakingModal.instanceIdPromise = null;
+        throw error;
+      });
+
+    return MatchmakingModal.instanceIdPromise;
+  }
+
   protected async onOpen(): Promise<void> {
     const userMe = await getUserMe();
     // Early return if modal was closed during async operation
diff --git a/src/client/NewsModal.ts b/src/client/NewsModal.ts
index dfd85ec92..e5eafdac1 100644
--- a/src/client/NewsModal.ts
+++ b/src/client/NewsModal.ts
@@ -3,12 +3,11 @@ import { resolveMarkdown } from "lit-markdown";
 import { customElement, property, query } from "lit/decorators.js";
 import version from "resources/version.txt?raw";
 import { translateText } from "../client/Utils";
+import { assetUrl } from "../core/AssetUrls";
 import "./components/baseComponents/Modal";
 import { BaseModal } from "./components/BaseModal";
 import { modalHeader } from "./components/ui/ModalHeader";
 import { normalizeNewsMarkdown } from "./NewsMarkdown";
-import changelog from "/changelog.md?url";
-import megaphone from "/images/Megaphone.svg?url";
 
 @customElement("news-modal")
 export class NewsModal extends BaseModal {
@@ -62,7 +61,7 @@ export class NewsModal extends BaseModal {
   protected onOpen(): void {
     if (!this.initialized) {
       this.initialized = true;
-      fetch(`${changelog}?v=${encodeURIComponent(version.trim())}`)
+      fetch(assetUrl("changelog.md"))
         .then((response) => (response.ok ? response.text() : "Failed to load"))
         .then((markdown) => normalizeNewsMarkdown(markdown))
         .then((markdown) => (this.markdown = markdown))
@@ -102,7 +101,7 @@ export class NewsButton extends LitElement {
       >
         <img
           class="size-[48px] dark:invert"
-          src="${megaphone}"
+          src="${assetUrl("images/Megaphone.svg")}"
           alt=${translateText("news.title")}
         />
       </button>
diff --git a/src/client/SinglePlayerModal.ts b/src/client/SinglePlayerModal.ts
index c93fa9edd..f11999594 100644
--- a/src/client/SinglePlayerModal.ts
+++ b/src/client/SinglePlayerModal.ts
@@ -2,6 +2,7 @@ import { TemplateResult, html } from "lit";
 import { customElement, state } from "lit/decorators.js";
 import { translateText } from "../client/Utils";
 import { UserMeResponse } from "../core/ApiSchemas";
+import { assetUrl } from "../core/AssetUrls";
 import {
   Difficulty,
   GameMapSize,
@@ -244,7 +245,7 @@ export class SinglePlayerModal extends BaseModal {
                   : "text-white/60"}"
               >
                 <img
-                  src="/images/MedalIconWhite.svg"
+                  src=${assetUrl("images/MedalIconWhite.svg")}
                   class="w-4 h-4 opacity-80 shrink-0"
                   style="${this.showAchievements
                     ? ""
diff --git a/src/client/TerrainMapFileLoader.ts b/src/client/TerrainMapFileLoader.ts
index c3b185ac9..f159eee88 100644
--- a/src/client/TerrainMapFileLoader.ts
+++ b/src/client/TerrainMapFileLoader.ts
@@ -1,6 +1,6 @@
+import { assetUrl } from "../core/AssetUrls";
 import { FetchGameMapLoader } from "../core/game/FetchGameMapLoader";
 
-export const terrainMapFileLoader = new FetchGameMapLoader(
-  `/maps`,
-  window.GIT_COMMIT,
+export const terrainMapFileLoader = new FetchGameMapLoader((path) =>
+  assetUrl(`maps/${path}`),
 );
diff --git a/src/client/TroubleshootingModal.ts b/src/client/TroubleshootingModal.ts
index 6c3343e76..30bb6da3c 100644
--- a/src/client/TroubleshootingModal.ts
+++ b/src/client/TroubleshootingModal.ts
@@ -1,5 +1,6 @@
 import { html } from "lit";
 import { customElement, property } from "lit/decorators.js";
+import { assetUrl } from "../core/AssetUrls";
 import { translateText } from "./Utils";
 import { BaseModal } from "./components/BaseModal";
 import "./components/baseComponents/Modal";
@@ -8,7 +9,7 @@ import {
   collectGraphicsDiagnostics,
   GraphicsDiagnostics,
 } from "./utilities/Diagnostic";
-import infoIcon from "/images/InfoIcon.svg?url";
+const infoIcon = assetUrl("images/InfoIcon.svg");
 
 @customElement("troubleshooting-modal")
 export class TroubleshootingModal extends BaseModal {
diff --git a/src/client/components/Footer.ts b/src/client/components/Footer.ts
index db2f9c0e1..ebf8ffe81 100644
--- a/src/client/components/Footer.ts
+++ b/src/client/components/Footer.ts
@@ -1,5 +1,6 @@
 import { LitElement, html } from "lit";
 import { customElement } from "lit/decorators.js";
+import { assetUrl } from "../../core/AssetUrls";
 
 @customElement("page-footer")
 export class Footer extends LitElement {
@@ -22,7 +23,7 @@ export class Footer extends LitElement {
             class="opacity-60 hover:opacity-100 hover:scale-110 transition-all"
           >
             <img
-              src="/icons/github-mark-white.svg"
+              src=${assetUrl("icons/github-mark-white.svg")}
               data-i18n-alt="news.github_link"
               class="h-6 w-6 lg:h-7 lg:w-7 object-contain pointer-events-none"
               draggable="false"
@@ -68,7 +69,7 @@ export class Footer extends LitElement {
             class="opacity-60 hover:opacity-100 hover:scale-110 transition-all"
           >
             <img
-              src="/icons/wiki-logo.svg"
+              src=${assetUrl("icons/wiki-logo.svg")}
               data-i18n-alt="main.wiki"
               class="h-6 w-6 lg:h-7 lg:w-7 object-contain pointer-events-none"
               draggable="false"
diff --git a/src/client/components/baseComponents/ranking/PlayerRow.ts b/src/client/components/baseComponents/ranking/PlayerRow.ts
index 612569192..b954de0e3 100644
--- a/src/client/components/baseComponents/ranking/PlayerRow.ts
+++ b/src/client/components/baseComponents/ranking/PlayerRow.ts
@@ -5,6 +5,7 @@ import {
   GOLD_INDEX_TRAIN_OTHER,
   GOLD_INDEX_TRAIN_SELF,
 } from "src/core/StatsSchemas";
+import { assetUrl } from "../../../../core/AssetUrls";
 import { renderNumber } from "../../../Utils";
 import { PlayerInfo, RankType } from "./GameInfoRanking";
 
@@ -54,7 +55,7 @@ export class PlayerRow extends LitElement {
   private renderCrownIcon() {
     return html`
       <img
-        src="/images/CrownIcon.svg"
+        src=${assetUrl("images/CrownIcon.svg")}
         class="absolute -top-0.75 left-4 size-3.75 sm:-top-1.75 sm:left-7.5 sm:size-5"
       />
     `;
@@ -192,7 +193,10 @@ export class PlayerRow extends LitElement {
         >
           ${renderNumber(this.score)}
         </div>
-        <img src="/images/GoldCoinIcon.svg" class="size-3.5 sm:size-5 m-auto" />
+        <img
+          src=${assetUrl("images/GoldCoinIcon.svg")}
+          class="size-3.5 sm:size-5 m-auto"
+        />
       </div>
     `;
   }
@@ -211,7 +215,10 @@ export class PlayerRow extends LitElement {
           <div class="rounded-md text-sm leading-[1.9rem] text-center w-full">
             ${this.renderAllTrades()}
           </div>
-          <img src="/images/GoldCoinIcon.svg" class="w-5 size-3.5 sm:size-5" />
+          <img
+            src=${assetUrl("images/GoldCoinIcon.svg")}
+            class="w-5 size-3.5 sm:size-5"
+          />
         </div>
       </div>
     `;
@@ -249,7 +256,7 @@ export class PlayerRow extends LitElement {
       </div>`;
     } else if (this.player.flag) {
       return html`<img
-        src="/flags/${this.player.flag}.svg"
+        src=${assetUrl(`flags/${this.player.flag}.svg`)}
         class="min-w-7.5 h-7.5 sm:min-w-10 sm:h-10 shrink-0"
       />`;
     }
@@ -259,7 +266,7 @@ export class PlayerRow extends LitElement {
         class="size-7.5 leading-1.25 shrink-0 rounded-[50%] sm:size-10 sm:pt-2.5 sm:leading-3.5 border border-gray-200 text-center bg-slate-500"
       >
         <img
-          src="/images/ProfileIcon.svg"
+          src=${assetUrl("images/ProfileIcon.svg")}
           class="size-5 mt-0.5 sm:size-6.25 sm:-mt-1.25 m-auto"
         />
       </div>
diff --git a/src/client/components/map/MapDisplay.ts b/src/client/components/map/MapDisplay.ts
index 2318d9523..3cf5782af 100644
--- a/src/client/components/map/MapDisplay.ts
+++ b/src/client/components/map/MapDisplay.ts
@@ -1,5 +1,6 @@
 import { LitElement, html } from "lit";
 import { customElement, property, state } from "lit/decorators.js";
+import { assetUrl } from "../../../core/AssetUrls";
 import { Difficulty, GameMapType } from "../../../core/game/Game";
 import { terrainMapFileLoader } from "../../TerrainMapFileLoader";
 import { translateText } from "../../Utils";
@@ -143,8 +144,7 @@ export class MapDisplay extends LitElement {
     const wins = this.readWins();
     return medalOrder.map((medal) => {
       const earned = wins.has(medal);
-      const mask =
-        "url('/images/MedalIconWhite.svg') no-repeat center / contain";
+      const mask = `url('${assetUrl("images/MedalIconWhite.svg")}') no-repeat center / contain`;
       return html`<div
         class="w-5 h-5 ${earned ? "opacity-100" : "opacity-25"}"
         style="background-color:${colors[
diff --git a/src/client/components/map/MapPicker.ts b/src/client/components/map/MapPicker.ts
index 7661cc0d5..2ad8da146 100644
--- a/src/client/components/map/MapPicker.ts
+++ b/src/client/components/map/MapPicker.ts
@@ -1,5 +1,6 @@
 import { LitElement, html } from "lit";
 import { customElement, property, state } from "lit/decorators.js";
+import { assetUrl } from "../../../core/AssetUrls";
 import {
   Difficulty,
   GameMapType,
@@ -7,7 +8,7 @@ import {
 } from "../../../core/game/Game";
 import { translateText } from "../../Utils";
 import "./MapDisplay";
-import randomMap from "/images/RandomMap.webp?url";
+const randomMap = assetUrl("images/RandomMap.webp");
 
 const featuredMaps: GameMapType[] = [
   GameMapType.World,
diff --git a/src/client/graphics/PlayerIcons.ts b/src/client/graphics/PlayerIcons.ts
index 672d82f2e..827974eff 100644
--- a/src/client/graphics/PlayerIcons.ts
+++ b/src/client/graphics/PlayerIcons.ts
@@ -1,18 +1,23 @@
+import { assetUrl } from "../../core/AssetUrls";
 import { AllPlayers, Nukes } from "../../core/game/Game";
 import { GameView, PlayerView } from "../../core/game/GameView";
-import allianceIcon from "/images/AllianceIcon.svg?url";
-import allianceIconFaded from "/images/AllianceIconFaded.svg?url";
-import allianceRequestBlackIcon from "/images/AllianceRequestBlackIcon.svg?url";
-import allianceRequestWhiteIcon from "/images/AllianceRequestWhiteIcon.svg?url";
-import crownIcon from "/images/CrownIcon.svg?url";
-import disconnectedIcon from "/images/DisconnectedIcon.svg?url";
-import embargoBlackIcon from "/images/EmbargoBlackIcon.svg?url";
-import embargoWhiteIcon from "/images/EmbargoWhiteIcon.svg?url";
-import nukeRedIcon from "/images/NukeIconRed.svg?url";
-import nukeWhiteIcon from "/images/NukeIconWhite.svg?url";
-import questionMarkIcon from "/images/QuestionMarkIcon.svg?url";
-import targetIcon from "/images/TargetIcon.svg?url";
-import traitorIcon from "/images/TraitorIcon.svg?url";
+const allianceIcon = assetUrl("images/AllianceIcon.svg");
+const allianceIconFaded = assetUrl("images/AllianceIconFaded.svg");
+const allianceRequestBlackIcon = assetUrl(
+  "images/AllianceRequestBlackIcon.svg",
+);
+const allianceRequestWhiteIcon = assetUrl(
+  "images/AllianceRequestWhiteIcon.svg",
+);
+const crownIcon = assetUrl("images/CrownIcon.svg");
+const disconnectedIcon = assetUrl("images/DisconnectedIcon.svg");
+const embargoBlackIcon = assetUrl("images/EmbargoBlackIcon.svg");
+const embargoWhiteIcon = assetUrl("images/EmbargoWhiteIcon.svg");
+const nukeRedIcon = assetUrl("images/NukeIconRed.svg");
+const nukeWhiteIcon = assetUrl("images/NukeIconWhite.svg");
+const questionMarkIcon = assetUrl("images/QuestionMarkIcon.svg");
+const targetIcon = assetUrl("images/TargetIcon.svg");
+const traitorIcon = assetUrl("images/TraitorIcon.svg");
 
 export type PlayerIconId =
   | "crown"
diff --git a/src/client/graphics/SpriteLoader.ts b/src/client/graphics/SpriteLoader.ts
index 36c4aca54..3d3d44669 100644
--- a/src/client/graphics/SpriteLoader.ts
+++ b/src/client/graphics/SpriteLoader.ts
@@ -1,17 +1,18 @@
 import { Colord } from "colord";
+import { assetUrl } from "../../core/AssetUrls";
 import { Theme } from "../../core/configuration/Config";
 import { TrainType, UnitType } from "../../core/game/Game";
 import { UnitView } from "../../core/game/GameView";
-import atomBombSprite from "/sprites/atombomb.png?url";
-import hydrogenBombSprite from "/sprites/hydrogenbomb.png?url";
-import mirvSprite from "/sprites/mirv2.png?url";
-import samMissileSprite from "/sprites/samMissile.png?url";
-import tradeShipSprite from "/sprites/tradeship.png?url";
-import trainCarriageSprite from "/sprites/trainCarriage.png?url";
-import trainLoadedCarriageSprite from "/sprites/trainCarriageLoaded.png?url";
-import trainEngineSprite from "/sprites/trainEngine.png?url";
-import transportShipSprite from "/sprites/transportship.png?url";
-import warshipSprite from "/sprites/warship.png?url";
+const atomBombSprite = assetUrl("sprites/atombomb.png");
+const hydrogenBombSprite = assetUrl("sprites/hydrogenbomb.png");
+const mirvSprite = assetUrl("sprites/mirv2.png");
+const samMissileSprite = assetUrl("sprites/samMissile.png");
+const tradeShipSprite = assetUrl("sprites/tradeship.png");
+const trainCarriageSprite = assetUrl("sprites/trainCarriage.png");
+const trainLoadedCarriageSprite = assetUrl("sprites/trainCarriageLoaded.png");
+const trainEngineSprite = assetUrl("sprites/trainEngine.png");
+const transportShipSprite = assetUrl("sprites/transportship.png");
+const warshipSprite = assetUrl("sprites/warship.png");
 
 // Can't reuse TrainType because "loaded" is not a type, just an attribute
 const TrainTypeSprite = {
diff --git a/src/client/graphics/layers/AttackingTroopsOverlay.ts b/src/client/graphics/layers/AttackingTroopsOverlay.ts
index ccad9f38b..09b33d897 100644
--- a/src/client/graphics/layers/AttackingTroopsOverlay.ts
+++ b/src/client/graphics/layers/AttackingTroopsOverlay.ts
@@ -1,3 +1,4 @@
+import { assetUrl } from "../../../core/AssetUrls";
 import { EventBus } from "../../../core/EventBus";
 import { Cell } from "../../../core/game/Game";
 import { GameView } from "../../../core/game/GameView";
@@ -6,8 +7,8 @@ import { AlternateViewEvent } from "../../InputHandler";
 import { renderTroops } from "../../Utils";
 import { TransformHandler } from "../TransformHandler";
 import { Layer } from "./Layer";
-import shieldIcon from "/images/ShieldIconWhite.svg?url";
-import swordIcon from "/images/SwordIconWhite.svg?url";
+const shieldIcon = assetUrl("images/ShieldIconWhite.svg");
+const swordIcon = assetUrl("images/SwordIconWhite.svg");
 
 export function troopAttackColor(
   attackerTroops: number,
diff --git a/src/client/graphics/layers/AttacksDisplay.ts b/src/client/graphics/layers/AttacksDisplay.ts
index f7f2a68e7..3fe621226 100644
--- a/src/client/graphics/layers/AttacksDisplay.ts
+++ b/src/client/graphics/layers/AttacksDisplay.ts
@@ -1,5 +1,6 @@
 import { html, LitElement } from "lit";
 import { customElement, state } from "lit/decorators.js";
+import { assetUrl } from "../../../core/AssetUrls";
 import { EventBus } from "../../../core/EventBus";
 import { MessageType, PlayerType, UnitType } from "../../../core/game/Game";
 import {
@@ -22,8 +23,8 @@ import {
   GoToPositionEvent,
   GoToUnitEvent,
 } from "./Leaderboard";
-import soldierIcon from "/images/SoldierIcon.svg?url";
-import swordIcon from "/images/SwordIcon.svg?url";
+const soldierIcon = assetUrl("images/SoldierIcon.svg");
+const swordIcon = assetUrl("images/SwordIcon.svg");
 
 @customElement("attacks-display")
 export class AttacksDisplay extends LitElement implements Layer {
diff --git a/src/client/graphics/layers/BuildMenu.ts b/src/client/graphics/layers/BuildMenu.ts
index 2d67f2b3c..797b4e568 100644
--- a/src/client/graphics/layers/BuildMenu.ts
+++ b/src/client/graphics/layers/BuildMenu.ts
@@ -1,6 +1,7 @@
 import { css, html, LitElement } from "lit";
 import { customElement, state } from "lit/decorators.js";
 import { translateText } from "../../../client/Utils";
+import { assetUrl } from "../../../core/AssetUrls";
 import { EventBus } from "../../../core/EventBus";
 import {
   BuildableUnit,
@@ -25,17 +26,17 @@ import { renderNumber } from "../../Utils";
 import { TransformHandler } from "../TransformHandler";
 import { UIState } from "../UIState";
 import { Layer } from "./Layer";
-import warshipIcon from "/images/BattleshipIconWhite.svg?url";
-import cityIcon from "/images/CityIconWhite.svg?url";
-import factoryIcon from "/images/FactoryIconWhite.svg?url";
-import goldCoinIcon from "/images/GoldCoinIcon.svg?url";
-import mirvIcon from "/images/MIRVIcon.svg?url";
-import missileSiloIcon from "/images/MissileSiloIconWhite.svg?url";
-import hydrogenBombIcon from "/images/MushroomCloudIconWhite.svg?url";
-import atomBombIcon from "/images/NukeIconWhite.svg?url";
-import portIcon from "/images/PortIcon.svg?url";
-import samlauncherIcon from "/images/SamLauncherIconWhite.svg?url";
-import shieldIcon from "/images/ShieldIconWhite.svg?url";
+const warshipIcon = assetUrl("images/BattleshipIconWhite.svg");
+const cityIcon = assetUrl("images/CityIconWhite.svg");
+const factoryIcon = assetUrl("images/FactoryIconWhite.svg");
+const goldCoinIcon = assetUrl("images/GoldCoinIcon.svg");
+const mirvIcon = assetUrl("images/MIRVIcon.svg");
+const missileSiloIcon = assetUrl("images/MissileSiloIconWhite.svg");
+const hydrogenBombIcon = assetUrl("images/MushroomCloudIconWhite.svg");
+const atomBombIcon = assetUrl("images/NukeIconWhite.svg");
+const portIcon = assetUrl("images/PortIcon.svg");
+const samlauncherIcon = assetUrl("images/SamLauncherIconWhite.svg");
+const shieldIcon = assetUrl("images/ShieldIconWhite.svg");
 
 export interface BuildItemDisplay {
   unitType: PlayerBuildableUnitType;
diff --git a/src/client/graphics/layers/ControlPanel.ts b/src/client/graphics/layers/ControlPanel.ts
index 719272804..033e34771 100644
--- a/src/client/graphics/layers/ControlPanel.ts
+++ b/src/client/graphics/layers/ControlPanel.ts
@@ -1,5 +1,6 @@
 import { LitElement, html } from "lit";
 import { customElement, state } from "lit/decorators.js";
+import { assetUrl } from "../../../core/AssetUrls";
 import { EventBus } from "../../../core/EventBus";
 import { Gold } from "../../../core/game/Game";
 import { GameView } from "../../../core/game/GameView";
@@ -8,9 +9,9 @@ import { AttackRatioEvent } from "../../InputHandler";
 import { renderNumber, renderTroops } from "../../Utils";
 import { UIState } from "../UIState";
 import { Layer } from "./Layer";
-import goldCoinIcon from "/images/GoldCoinIcon.svg?url";
-import soldierIcon from "/images/SoldierIcon.svg?url";
-import swordIcon from "/images/SwordIcon.svg?url";
+const goldCoinIcon = assetUrl("images/GoldCoinIcon.svg");
+const soldierIcon = assetUrl("images/SoldierIcon.svg");
+const swordIcon = assetUrl("images/SwordIcon.svg");
 
 @customElement("control-panel")
 export class ControlPanel extends LitElement implements Layer {
diff --git a/src/client/graphics/layers/EventsDisplay.ts b/src/client/graphics/layers/EventsDisplay.ts
index 14e546ce9..0524c992a 100644
--- a/src/client/graphics/layers/EventsDisplay.ts
+++ b/src/client/graphics/layers/EventsDisplay.ts
@@ -2,6 +2,7 @@ import { html, LitElement } from "lit";
 import { customElement, query, state } from "lit/decorators.js";
 import { DirectiveResult } from "lit/directive.js";
 import { unsafeHTML, UnsafeHTMLDirective } from "lit/directives/unsafe-html.js";
+import { assetUrl } from "../../../core/AssetUrls";
 import { EventBus } from "../../../core/EventBus";
 import {
   AllPlayers,
@@ -37,11 +38,11 @@ import { GoToPlayerEvent, GoToUnitEvent } from "./Leaderboard";
 
 import { getMessageTypeClasses, translateText } from "../../Utils";
 import { UIState } from "../UIState";
-import allianceIcon from "/images/AllianceIconWhite.svg?url";
-import chatIcon from "/images/ChatIconWhite.svg?url";
-import donateGoldIcon from "/images/DonateGoldIconWhite.svg?url";
-import nukeIcon from "/images/NukeIconWhite.svg?url";
-import swordIcon from "/images/SwordIconWhite.svg?url";
+const allianceIcon = assetUrl("images/AllianceIconWhite.svg");
+const chatIcon = assetUrl("images/ChatIconWhite.svg");
+const donateGoldIcon = assetUrl("images/DonateGoldIconWhite.svg");
+const nukeIcon = assetUrl("images/NukeIconWhite.svg");
+const swordIcon = assetUrl("images/SwordIconWhite.svg");
 
 interface GameEvent {
   description: string;
diff --git a/src/client/graphics/layers/GameLeftSidebar.ts b/src/client/graphics/layers/GameLeftSidebar.ts
index 9092670e8..79b7bf76e 100644
--- a/src/client/graphics/layers/GameLeftSidebar.ts
+++ b/src/client/graphics/layers/GameLeftSidebar.ts
@@ -1,6 +1,7 @@
 import { Colord } from "colord";
 import { html, LitElement } from "lit";
 import { customElement, state } from "lit/decorators.js";
+import { assetUrl } from "../../../core/AssetUrls";
 import { EventBus } from "../../../core/EventBus";
 import { GameMode, Team } from "../../../core/game/Game";
 import { GameView } from "../../../core/game/GameView";
@@ -9,10 +10,12 @@ import { getTranslatedPlayerTeamLabel, translateText } from "../../Utils";
 import { ImmunityBarVisibleEvent } from "./ImmunityTimer";
 import { Layer } from "./Layer";
 import { SpawnBarVisibleEvent } from "./SpawnTimer";
-import leaderboardRegularIcon from "/images/LeaderboardIconRegularWhite.svg?url";
-import leaderboardSolidIcon from "/images/LeaderboardIconSolidWhite.svg?url";
-import teamRegularIcon from "/images/TeamIconRegularWhite.svg?url";
-import teamSolidIcon from "/images/TeamIconSolidWhite.svg?url";
+const leaderboardRegularIcon = assetUrl(
+  "images/LeaderboardIconRegularWhite.svg",
+);
+const leaderboardSolidIcon = assetUrl("images/LeaderboardIconSolidWhite.svg");
+const teamRegularIcon = assetUrl("images/TeamIconRegularWhite.svg");
+const teamSolidIcon = assetUrl("images/TeamIconSolidWhite.svg");
 
 @customElement("game-left-sidebar")
 export class GameLeftSidebar extends LitElement implements Layer {
diff --git a/src/client/graphics/layers/GameRightSidebar.ts b/src/client/graphics/layers/GameRightSidebar.ts
index 8b1fc3169..67f5ed1dc 100644
--- a/src/client/graphics/layers/GameRightSidebar.ts
+++ b/src/client/graphics/layers/GameRightSidebar.ts
@@ -1,5 +1,6 @@
 import { html, LitElement } from "lit";
 import { customElement, state } from "lit/decorators.js";
+import { assetUrl } from "../../../core/AssetUrls";
 import { EventBus } from "../../../core/EventBus";
 import { GameType } from "../../../core/game/Game";
 import { GameView } from "../../../core/game/GameView";
@@ -12,11 +13,11 @@ import { Layer } from "./Layer";
 import { ShowReplayPanelEvent } from "./ReplayPanel";
 import { ShowSettingsModalEvent } from "./SettingsModal";
 import { SpawnBarVisibleEvent } from "./SpawnTimer";
-import exitIcon from "/images/ExitIconWhite.svg?url";
-import FastForwardIconSolid from "/images/FastForwardIconSolidWhite.svg?url";
-import pauseIcon from "/images/PauseIconWhite.svg?url";
-import playIcon from "/images/PlayIconWhite.svg?url";
-import settingsIcon from "/images/SettingIconWhite.svg?url";
+const exitIcon = assetUrl("images/ExitIconWhite.svg");
+const FastForwardIconSolid = assetUrl("images/FastForwardIconSolidWhite.svg");
+const pauseIcon = assetUrl("images/PauseIconWhite.svg");
+const playIcon = assetUrl("images/PlayIconWhite.svg");
+const settingsIcon = assetUrl("images/SettingIconWhite.svg");
 
 @customElement("game-right-sidebar")
 export class GameRightSidebar extends LitElement implements Layer {
diff --git a/src/client/graphics/layers/MainRadialMenu.ts b/src/client/graphics/layers/MainRadialMenu.ts
index 15ffd7b6e..b6adba929 100644
--- a/src/client/graphics/layers/MainRadialMenu.ts
+++ b/src/client/graphics/layers/MainRadialMenu.ts
@@ -1,5 +1,6 @@
 import { LitElement } from "lit";
 import { customElement } from "lit/decorators.js";
+import { assetUrl } from "../../../core/AssetUrls";
 import { EventBus } from "../../../core/EventBus";
 import { PlayerActions } from "../../../core/game/Game";
 import { TileRef } from "../../../core/game/GameMap";
@@ -19,8 +20,8 @@ import {
   MenuElementParams,
   rootMenuElement,
 } from "./RadialMenuElements";
-import donateTroopIcon from "/images/DonateTroopIconWhite.svg?url";
-import swordIcon from "/images/SwordIconWhite.svg?url";
+const donateTroopIcon = assetUrl("images/DonateTroopIconWhite.svg");
+const swordIcon = assetUrl("images/SwordIconWhite.svg");
 
 import { ContextMenuEvent } from "../../InputHandler";
 
diff --git a/src/client/graphics/layers/NameLayer.ts b/src/client/graphics/layers/NameLayer.ts
index ed5184a39..2cee0dbe0 100644
--- a/src/client/graphics/layers/NameLayer.ts
+++ b/src/client/graphics/layers/NameLayer.ts
@@ -1,3 +1,4 @@
+import { assetUrl } from "../../../core/AssetUrls";
 import { renderPlayerFlag } from "../../../core/CustomFlag";
 import { EventBus } from "../../../core/EventBus";
 import { PseudoRandom } from "../../../core/PseudoRandom";
@@ -229,7 +230,7 @@ export class NameLayer implements Layer {
       } else if (flag !== undefined && flag !== null) {
         const flagImg = document.createElement("img");
         applyFlagStyles(flagImg);
-        flagImg.src = "/flags/" + flag + ".svg";
+        flagImg.src = assetUrl(`flags/${flag}.svg`);
         nameDiv.appendChild(flagImg);
       }
     }
diff --git a/src/client/graphics/layers/PlayerInfoOverlay.ts b/src/client/graphics/layers/PlayerInfoOverlay.ts
index bdf24837a..a332eaaad 100644
--- a/src/client/graphics/layers/PlayerInfoOverlay.ts
+++ b/src/client/graphics/layers/PlayerInfoOverlay.ts
@@ -1,6 +1,7 @@
 import { LitElement, TemplateResult, html } from "lit";
 import { ref } from "lit-html/directives/ref.js";
 import { customElement, property, state } from "lit/decorators.js";
+import { assetUrl } from "../../../core/AssetUrls";
 import { renderPlayerFlag } from "../../../core/CustomFlag";
 import { EventBus } from "../../../core/EventBus";
 import {
@@ -31,15 +32,15 @@ import { ImmunityBarVisibleEvent } from "./ImmunityTimer";
 import { Layer } from "./Layer";
 import { CloseRadialMenuEvent } from "./RadialMenu";
 import { SpawnBarVisibleEvent } from "./SpawnTimer";
-import allianceIcon from "/images/AllianceIcon.svg?url";
-import warshipIcon from "/images/BattleshipIconWhite.svg?url";
-import cityIcon from "/images/CityIconWhite.svg?url";
-import factoryIcon from "/images/FactoryIconWhite.svg?url";
-import goldCoinIcon from "/images/GoldCoinIcon.svg?url";
-import missileSiloIcon from "/images/MissileSiloIconWhite.svg?url";
-import portIcon from "/images/PortIcon.svg?url";
-import samLauncherIcon from "/images/SamLauncherIconWhite.svg?url";
-import soldierIcon from "/images/SoldierIcon.svg?url";
+const allianceIcon = assetUrl("images/AllianceIcon.svg");
+const warshipIcon = assetUrl("images/BattleshipIconWhite.svg");
+const cityIcon = assetUrl("images/CityIconWhite.svg");
+const factoryIcon = assetUrl("images/FactoryIconWhite.svg");
+const goldCoinIcon = assetUrl("images/GoldCoinIcon.svg");
+const missileSiloIcon = assetUrl("images/MissileSiloIconWhite.svg");
+const portIcon = assetUrl("images/PortIcon.svg");
+const samLauncherIcon = assetUrl("images/SamLauncherIconWhite.svg");
+const soldierIcon = assetUrl("images/SoldierIcon.svg");
 
 function euclideanDistWorld(
   coord: { x: number; y: number },
@@ -377,7 +378,7 @@ export class PlayerInfoOverlay extends LitElement implements Layer {
                   ></div>`
                 : html`<img
                     class="h-6 aspect-3/4"
-                    src=${"/flags/" + player.cosmetics.flag! + ".svg"}
+                    src=${assetUrl(`flags/${player.cosmetics.flag!}.svg`)}
                   />`
               : html``}
             <span>${player.displayName()}</span>
diff --git a/src/client/graphics/layers/PlayerModerationModal.ts b/src/client/graphics/layers/PlayerModerationModal.ts
index e08230ce2..2bf570e31 100644
--- a/src/client/graphics/layers/PlayerModerationModal.ts
+++ b/src/client/graphics/layers/PlayerModerationModal.ts
@@ -1,13 +1,14 @@
 import { html, LitElement } from "lit";
 import { customElement, property } from "lit/decorators.js";
+import { assetUrl } from "../../../core/AssetUrls";
 import { EventBus } from "../../../core/EventBus";
 import { PlayerType } from "../../../core/game/Game";
 import { PlayerView } from "../../../core/game/GameView";
 import { actionButton } from "../../components/ui/ActionButton";
 import { SendKickPlayerIntentEvent } from "../../Transport";
 import { translateText } from "../../Utils";
-import kickIcon from "/images/ExitIconWhite.svg?url";
-import shieldIcon from "/images/ShieldIconWhite.svg?url";
+const kickIcon = assetUrl("images/ExitIconWhite.svg");
+const shieldIcon = assetUrl("images/ShieldIconWhite.svg");
 
 @customElement("player-moderation-modal")
 export class PlayerModerationModal extends LitElement {
diff --git a/src/client/graphics/layers/PlayerPanel.ts b/src/client/graphics/layers/PlayerPanel.ts
index 0fb3b304f..17dc419bd 100644
--- a/src/client/graphics/layers/PlayerPanel.ts
+++ b/src/client/graphics/layers/PlayerPanel.ts
@@ -1,6 +1,7 @@
 import { html, LitElement } from "lit";
 import { customElement, state } from "lit/decorators.js";
 import Countries from "resources/countries.json" with { type: "json" };
+import { assetUrl } from "../../../core/AssetUrls";
 import { EventBus } from "../../../core/EventBus";
 import {
   AllPlayers,
@@ -39,17 +40,17 @@ import { EmojiTable } from "./EmojiTable";
 import { Layer } from "./Layer";
 import "./PlayerModerationModal";
 import "./SendResourceModal";
-import allianceIcon from "/images/AllianceIconWhite.svg?url";
-import chatIcon from "/images/ChatIconWhite.svg?url";
-import donateGoldIcon from "/images/DonateGoldIconWhite.svg?url";
-import donateTroopIcon from "/images/DonateTroopIconWhite.svg?url";
-import emojiIcon from "/images/EmojiIconWhite.svg?url";
-import shieldIcon from "/images/ShieldIconWhite.svg?url";
-import stopTradingIcon from "/images/StopIconWhite.png?url";
-import targetIcon from "/images/TargetIconWhite.svg?url";
-import startTradingIcon from "/images/TradingIconWhite.png?url";
-import traitorIcon from "/images/TraitorIconLightRed.svg?url";
-import breakAllianceIcon from "/images/TraitorIconWhite.svg?url";
+const allianceIcon = assetUrl("images/AllianceIconWhite.svg");
+const chatIcon = assetUrl("images/ChatIconWhite.svg");
+const donateGoldIcon = assetUrl("images/DonateGoldIconWhite.svg");
+const donateTroopIcon = assetUrl("images/DonateTroopIconWhite.svg");
+const emojiIcon = assetUrl("images/EmojiIconWhite.svg");
+const shieldIcon = assetUrl("images/ShieldIconWhite.svg");
+const stopTradingIcon = assetUrl("images/StopIconWhite.png");
+const targetIcon = assetUrl("images/TargetIconWhite.svg");
+const startTradingIcon = assetUrl("images/TradingIconWhite.png");
+const traitorIcon = assetUrl("images/TraitorIconLightRed.svg");
+const breakAllianceIcon = assetUrl("images/TraitorIconWhite.svg");
 
 @customElement("player-panel")
 export class PlayerPanel extends LitElement implements Layer {
@@ -493,7 +494,7 @@ export class PlayerPanel extends LitElement implements Layer {
       <div class="flex items-center gap-2.5 flex-wrap">
         ${country && typeof flagCode === "string"
           ? html`<img
-              src="/flags/${encodeURIComponent(flagCode)}.svg"
+              src=${assetUrl(`flags/${encodeURIComponent(flagCode)}.svg`)}
               alt=${country?.name ?? "Flag"}
               class="h-10 w-10 rounded-full object-cover"
               @error=${(e: Event) => {
diff --git a/src/client/graphics/layers/RadialMenu.ts b/src/client/graphics/layers/RadialMenu.ts
index 8cebec9c5..9f8b6c654 100644
--- a/src/client/graphics/layers/RadialMenu.ts
+++ b/src/client/graphics/layers/RadialMenu.ts
@@ -1,4 +1,5 @@
 import * as d3 from "d3";
+import { assetUrl } from "../../../core/AssetUrls";
 import { EventBus, GameEvent } from "../../../core/EventBus";
 import { CloseViewEvent } from "../../InputHandler";
 import { getSvgAspectRatio, translateText } from "../../Utils";
@@ -9,7 +10,7 @@ import {
   MenuElementParams,
   TooltipKey,
 } from "./RadialMenuElements";
-import backIcon from "/images/BackIconWhite.svg?url";
+const backIcon = assetUrl("images/BackIconWhite.svg");
 
 function resolveColor(
   item: MenuElement,
diff --git a/src/client/graphics/layers/RadialMenuElements.ts b/src/client/graphics/layers/RadialMenuElements.ts
index 2f55a55e6..b24c24b03 100644
--- a/src/client/graphics/layers/RadialMenuElements.ts
+++ b/src/client/graphics/layers/RadialMenuElements.ts
@@ -1,3 +1,4 @@
+import { assetUrl } from "../../../core/AssetUrls";
 import { Config } from "../../../core/configuration/Config";
 import {
   AllPlayers,
@@ -20,18 +21,18 @@ import { PlayerPanel } from "./PlayerPanel";
 import { TooltipItem } from "./RadialMenu";
 
 import { EventBus } from "../../../core/EventBus";
-import allianceIcon from "/images/AllianceIconWhite.svg?url";
-import boatIcon from "/images/BoatIconWhite.svg?url";
-import buildIcon from "/images/BuildIconWhite.svg?url";
-import chatIcon from "/images/ChatIconWhite.svg?url";
-import donateGoldIcon from "/images/DonateGoldIconWhite.svg?url";
-import donateTroopIcon from "/images/DonateTroopIconWhite.svg?url";
-import emojiIcon from "/images/EmojiIconWhite.svg?url";
-import infoIcon from "/images/InfoIcon.svg?url";
-import swordIcon from "/images/SwordIconWhite.svg?url";
-import targetIcon from "/images/TargetIconWhite.svg?url";
-import traitorIcon from "/images/TraitorIconWhite.svg?url";
-import xIcon from "/images/XIcon.svg?url";
+const allianceIcon = assetUrl("images/AllianceIconWhite.svg");
+const boatIcon = assetUrl("images/BoatIconWhite.svg");
+const buildIcon = assetUrl("images/BuildIconWhite.svg");
+const chatIcon = assetUrl("images/ChatIconWhite.svg");
+const donateGoldIcon = assetUrl("images/DonateGoldIconWhite.svg");
+const donateTroopIcon = assetUrl("images/DonateTroopIconWhite.svg");
+const emojiIcon = assetUrl("images/EmojiIconWhite.svg");
+const infoIcon = assetUrl("images/InfoIcon.svg");
+const swordIcon = assetUrl("images/SwordIconWhite.svg");
+const targetIcon = assetUrl("images/TargetIconWhite.svg");
+const traitorIcon = assetUrl("images/TraitorIconWhite.svg");
+const xIcon = assetUrl("images/XIcon.svg");
 
 export interface MenuElementParams {
   myPlayer: PlayerView;
diff --git a/src/client/graphics/layers/SettingsModal.ts b/src/client/graphics/layers/SettingsModal.ts
index 8a285a661..2e3c9f532 100644
--- a/src/client/graphics/layers/SettingsModal.ts
+++ b/src/client/graphics/layers/SettingsModal.ts
@@ -2,25 +2,26 @@ import { html, LitElement } from "lit";
 import { customElement, property, query, state } from "lit/decorators.js";
 import { crazyGamesSDK } from "src/client/CrazyGamesSDK";
 import { PauseGameIntentEvent } from "src/client/Transport";
+import { assetUrl } from "../../../core/AssetUrls";
 import { EventBus } from "../../../core/EventBus";
 import { UserSettings } from "../../../core/game/UserSettings";
 import { AlternateViewEvent, RefreshGraphicsEvent } from "../../InputHandler";
 import { translateText } from "../../Utils";
 import SoundManager from "../../sound/SoundManager";
 import { Layer } from "./Layer";
-import structureIcon from "/images/CityIconWhite.svg?url";
-import cursorPriceIcon from "/images/CursorPriceIconWhite.svg?url";
-import darkModeIcon from "/images/DarkModeIconWhite.svg?url";
-import emojiIcon from "/images/EmojiIconWhite.svg?url";
-import exitIcon from "/images/ExitIconWhite.svg?url";
-import explosionIcon from "/images/ExplosionIconWhite.svg?url";
-import mouseIcon from "/images/MouseIconWhite.svg?url";
-import ninjaIcon from "/images/NinjaIconWhite.svg?url";
-import settingsIcon from "/images/SettingIconWhite.svg?url";
-import sirenIcon from "/images/SirenIconWhite.svg?url";
-import swordIcon from "/images/SwordIconWhite.svg?url";
-import treeIcon from "/images/TreeIconWhite.svg?url";
-import musicIcon from "/images/music.svg?url";
+const structureIcon = assetUrl("images/CityIconWhite.svg");
+const cursorPriceIcon = assetUrl("images/CursorPriceIconWhite.svg");
+const darkModeIcon = assetUrl("images/DarkModeIconWhite.svg");
+const emojiIcon = assetUrl("images/EmojiIconWhite.svg");
+const exitIcon = assetUrl("images/ExitIconWhite.svg");
+const explosionIcon = assetUrl("images/ExplosionIconWhite.svg");
+const mouseIcon = assetUrl("images/MouseIconWhite.svg");
+const ninjaIcon = assetUrl("images/NinjaIconWhite.svg");
+const settingsIcon = assetUrl("images/SettingIconWhite.svg");
+const sirenIcon = assetUrl("images/SirenIconWhite.svg");
+const swordIcon = assetUrl("images/SwordIconWhite.svg");
+const treeIcon = assetUrl("images/TreeIconWhite.svg");
+const musicIcon = assetUrl("images/music.svg");
 
 export class ShowSettingsModalEvent {
   constructor(
diff --git a/src/client/graphics/layers/StructureDrawingUtils.ts b/src/client/graphics/layers/StructureDrawingUtils.ts
index 663547170..52a1b4951 100644
--- a/src/client/graphics/layers/StructureDrawingUtils.ts
+++ b/src/client/graphics/layers/StructureDrawingUtils.ts
@@ -1,4 +1,5 @@
 import * as PIXI from "pixi.js";
+import { assetUrl } from "../../../core/AssetUrls";
 import { Theme } from "../../../core/configuration/Config";
 import {
   Cell,
@@ -7,12 +8,12 @@ import {
 } from "../../../core/game/Game";
 import { GameView, PlayerView, UnitView } from "../../../core/game/GameView";
 import { TransformHandler } from "../TransformHandler";
-import anchorIcon from "/images/AnchorIcon.png?url";
-import cityIcon from "/images/CityIcon.png?url";
-import factoryIcon from "/images/FactoryUnit.png?url";
-import missileSiloIcon from "/images/MissileSiloUnit.png?url";
-import SAMMissileIcon from "/images/SamLauncherUnit.png?url";
-import shieldIcon from "/images/ShieldIcon.png?url";
+const anchorIcon = assetUrl("images/AnchorIcon.png");
+const cityIcon = assetUrl("images/CityIcon.png");
+const factoryIcon = assetUrl("images/FactoryUnit.png");
+const missileSiloIcon = assetUrl("images/MissileSiloUnit.png");
+const SAMMissileIcon = assetUrl("images/SamLauncherUnit.png");
+const shieldIcon = assetUrl("images/ShieldIcon.png");
 
 export const STRUCTURE_SHAPES: Partial<Record<UnitType, ShapeType>> = {
   [UnitType.City]: "circle",
diff --git a/src/client/graphics/layers/StructureIconsLayer.ts b/src/client/graphics/layers/StructureIconsLayer.ts
index a3018d542..3430fae28 100644
--- a/src/client/graphics/layers/StructureIconsLayer.ts
+++ b/src/client/graphics/layers/StructureIconsLayer.ts
@@ -2,6 +2,7 @@ import { extend } from "colord";
 import a11yPlugin from "colord/plugins/a11y";
 import { OutlineFilter } from "pixi-filters";
 import * as PIXI from "pixi.js";
+import { assetUrl } from "../../../core/AssetUrls";
 import { Theme } from "../../../core/configuration/Config";
 import { EventBus } from "../../../core/EventBus";
 import { wouldNukeBreakAlliance } from "../../../core/execution/Util";
@@ -42,7 +43,7 @@ import {
   STRUCTURE_SHAPES,
   ZOOM_THRESHOLD,
 } from "./StructureDrawingUtils";
-import bitmapFont from "/fonts/round_6x6_modified.xml?url";
+const bitmapFont = assetUrl("fonts/round_6x6_modified.xml");
 
 /** True for nuke types (AtomBomb, HydrogenBomb): ghost is preserved after placement so user can place multiple or keep selection (Enter/key confirm). */
 export function shouldPreserveGhostAfterBuild(unitType: UnitType): boolean {
diff --git a/src/client/graphics/layers/StructureLayer.ts b/src/client/graphics/layers/StructureLayer.ts
index 819c4e3f7..32d836256 100644
--- a/src/client/graphics/layers/StructureLayer.ts
+++ b/src/client/graphics/layers/StructureLayer.ts
@@ -1,4 +1,5 @@
 import { colord, Colord } from "colord";
+import { assetUrl } from "../../../core/AssetUrls";
 import { Theme } from "../../../core/configuration/Config";
 import { EventBus } from "../../../core/EventBus";
 import { TransformHandler } from "../TransformHandler";
@@ -8,12 +9,12 @@ import { Cell, UnitType } from "../../../core/game/Game";
 import { euclDistFN, isometricDistFN } from "../../../core/game/GameMap";
 import { GameUpdateType } from "../../../core/game/GameUpdates";
 import { GameView, UnitView } from "../../../core/game/GameView";
-import cityIcon from "/images/buildings/cityAlt1.png?url";
-import factoryIcon from "/images/buildings/factoryAlt1.png?url";
-import shieldIcon from "/images/buildings/fortAlt3.png?url";
-import anchorIcon from "/images/buildings/port1.png?url";
-import missileSiloIcon from "/images/buildings/silo1.png?url";
-import SAMMissileIcon from "/images/buildings/silo4.png?url";
+const cityIcon = assetUrl("images/buildings/cityAlt1.png");
+const factoryIcon = assetUrl("images/buildings/factoryAlt1.png");
+const shieldIcon = assetUrl("images/buildings/fortAlt3.png");
+const anchorIcon = assetUrl("images/buildings/port1.png");
+const missileSiloIcon = assetUrl("images/buildings/silo1.png");
+const SAMMissileIcon = assetUrl("images/buildings/silo4.png");
 
 const underConstructionColor = colord("rgb(150,150,150)");
 
diff --git a/src/client/graphics/layers/UnitDisplay.ts b/src/client/graphics/layers/UnitDisplay.ts
index d243ec94b..88f965f98 100644
--- a/src/client/graphics/layers/UnitDisplay.ts
+++ b/src/client/graphics/layers/UnitDisplay.ts
@@ -1,5 +1,6 @@
 import { html, LitElement } from "lit";
 import { customElement } from "lit/decorators.js";
+import { assetUrl } from "../../../core/AssetUrls";
 import { EventBus } from "../../../core/EventBus";
 import {
   BuildableUnit,
@@ -16,17 +17,17 @@ import {
 import { renderNumber, translateText } from "../../Utils";
 import { UIState } from "../UIState";
 import { Layer } from "./Layer";
-import warshipIcon from "/images/BattleshipIconWhite.svg?url";
-import cityIcon from "/images/CityIconWhite.svg?url";
-import factoryIcon from "/images/FactoryIconWhite.svg?url";
-import goldCoinIcon from "/images/GoldCoinIcon.svg?url";
-import mirvIcon from "/images/MIRVIcon.svg?url";
-import missileSiloIcon from "/images/MissileSiloIconWhite.svg?url";
-import hydrogenBombIcon from "/images/MushroomCloudIconWhite.svg?url";
-import atomBombIcon from "/images/NukeIconWhite.svg?url";
-import portIcon from "/images/PortIcon.svg?url";
-import samLauncherIcon from "/images/SamLauncherIconWhite.svg?url";
-import defensePostIcon from "/images/ShieldIconWhite.svg?url";
+const warshipIcon = assetUrl("images/BattleshipIconWhite.svg");
+const cityIcon = assetUrl("images/CityIconWhite.svg");
+const factoryIcon = assetUrl("images/FactoryIconWhite.svg");
+const goldCoinIcon = assetUrl("images/GoldCoinIcon.svg");
+const mirvIcon = assetUrl("images/MIRVIcon.svg");
+const missileSiloIcon = assetUrl("images/MissileSiloIconWhite.svg");
+const hydrogenBombIcon = assetUrl("images/MushroomCloudIconWhite.svg");
+const atomBombIcon = assetUrl("images/NukeIconWhite.svg");
+const portIcon = assetUrl("images/PortIcon.svg");
+const samLauncherIcon = assetUrl("images/SamLauncherIconWhite.svg");
+const defensePostIcon = assetUrl("images/ShieldIconWhite.svg");
 
 @customElement("unit-display")
 export class UnitDisplay extends LitElement implements Layer {
diff --git a/src/client/sound/SoundManager.ts b/src/client/sound/SoundManager.ts
index 3624efcad..6e6e0e912 100644
--- a/src/client/sound/SoundManager.ts
+++ b/src/client/sound/SoundManager.ts
@@ -2,7 +2,8 @@ import { Howl } from "howler";
 import of4 from "../../../proprietary/sounds/music/of4.mp3";
 import openfront from "../../../proprietary/sounds/music/openfront.mp3";
 import war from "../../../proprietary/sounds/music/war.mp3";
-import kaChingSound from "/sounds/effects/ka-ching.mp3?url";
+import { assetUrl } from "../../core/AssetUrls";
+const kaChingSound = assetUrl("sounds/effects/ka-ching.mp3");
 
 export enum SoundEffect {
   KaChing = "ka-ching",
diff --git a/src/client/vite-env.d.ts b/src/client/vite-env.d.ts
index 83679d71c..d00e00e09 100644
--- a/src/client/vite-env.d.ts
+++ b/src/client/vite-env.d.ts
@@ -10,11 +10,6 @@ declare module "*.md" {
   export default mdContent;
 }
 
-declare module "*.md?url" {
-  const mdUrl: string;
-  export default mdUrl;
-}
-
 declare module "*.html" {
   const htmlContent: string;
   export default htmlContent;
@@ -39,8 +34,3 @@ declare module "*.webp" {
   const webpContent: string;
   export default webpContent;
 }
-
-declare module "*.svg?url" {
-  const svgUrl: string;
-  export default svgUrl;
-}
diff --git a/src/core/AssetUrls.ts b/src/core/AssetUrls.ts
new file mode 100644
index 000000000..1f69f0abe
--- /dev/null
+++ b/src/core/AssetUrls.ts
@@ -0,0 +1,86 @@
+export type AssetManifest = Record<string, string>;
+
+function safeDecodeAssetSegment(segment: string): string {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}
+
+function assertSafeAssetSegment(segment: string): string {
+  const decodedSegment = safeDecodeAssetSegment(segment);
+  if (
+    segment === "." ||
+    segment === ".." ||
+    decodedSegment === "." ||
+    decodedSegment === ".."
+  ) {
+    throw new Error(`Invalid asset path segment: ${segment}`);
+  }
+  return decodedSegment;
+}
+
+export function encodeAssetPath(path: string): string {
+  return normalizeAssetPath(path)
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
+export function normalizeAssetPath(path: string): string {
+  const normalizedPath = path
+    .replace(/^\/+/, "")
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map((segment) => assertSafeAssetSegment(segment))
+    .join("/");
+
+  if (normalizedPath.length === 0) {
+    throw new Error("Asset path must not be empty");
+  }
+
+  return normalizedPath;
+}
+
+export function buildAssetUrl(
+  path: string,
+  assetManifest: AssetManifest = {},
+): string {
+  const normalizedPath = normalizeAssetPath(path);
+
+  const directUrl = assetManifest[normalizedPath];
+  if (directUrl) {
+    return directUrl;
+  }
+
+  const directoryPrefix = `${normalizedPath}/`;
+  const hasNestedAssets = Object.keys(assetManifest).some((manifestPath) =>
+    manifestPath.startsWith(directoryPrefix),
+  );
+  if (hasNestedAssets) {
+    return `/_assets/${encodeAssetPath(normalizedPath)}`;
+  }
+
+  return `/${encodeAssetPath(normalizedPath)}`;
+}
+
+declare global {
+  var __ASSET_MANIFEST__: AssetManifest | undefined;
+
+  interface Window {
+    ASSET_MANIFEST?: AssetManifest;
+  }
+}
+
+export function getAssetManifest(): AssetManifest {
+  if (typeof window !== "undefined" && window.ASSET_MANIFEST !== undefined) {
+    return window.ASSET_MANIFEST;
+  }
+  return globalThis.__ASSET_MANIFEST__ ?? {};
+}
+
+export function assetUrl(path: string): string {
+  return buildAssetUrl(path, getAssetManifest());
+}
diff --git a/src/core/CustomFlag.ts b/src/core/CustomFlag.ts
index 3347e5e8f..663d4364d 100644
--- a/src/core/CustomFlag.ts
+++ b/src/core/CustomFlag.ts
@@ -1,3 +1,4 @@
+import { assetUrl } from "./AssetUrls";
 import { Cosmetics } from "./CosmeticSchemas";
 
 const ANIMATION_DURATIONS: Record<string, number> = {
@@ -39,7 +40,7 @@ export function renderPlayerFlag(
   for (const { layerKey, colorKey } of layers) {
     const layerName = cosmetics?.flag?.layers[layerKey]?.name ?? layerKey;
 
-    const mask = `/flags/custom/${layerName}.svg`;
+    const mask = assetUrl(`flags/custom/${layerName}.svg`);
     if (!mask) continue;
 
     const layer = document.createElement("div");
diff --git a/src/core/configuration/ConfigLoader.ts b/src/core/configuration/ConfigLoader.ts
index 15771873b..4987da1c3 100644
--- a/src/core/configuration/ConfigLoader.ts
+++ b/src/core/configuration/ConfigLoader.ts
@@ -9,6 +9,14 @@ import { prodConfig } from "./ProdConfig";
 
 export let cachedSC: ServerConfig | null = null;
 
+declare global {
+  interface Window {
+    BOOTSTRAP_CONFIG?: {
+      gameEnv?: string;
+    };
+  }
+}
+
 export async function getConfig(
   gameConfig: GameConfig,
   userSettings: UserSettings | null,
@@ -30,18 +38,13 @@ export async function getServerConfigFromClient(): Promise<ServerConfig> {
   if (cachedSC) {
     return cachedSC;
   }
-  const response = await fetch("/api/env");
 
-  if (!response.ok) {
-    throw new Error(
-      `Failed to fetch server config: ${response.status} ${response.statusText}`,
-    );
+  const bootstrapGameEnv = window.BOOTSTRAP_CONFIG?.gameEnv;
+  if (!bootstrapGameEnv) {
+    throw new Error("Missing bootstrap server config");
   }
-  const config = await response.json();
-  // Log the retrieved configuration
-  console.log("Server config loaded:", config);
 
-  cachedSC = getServerConfig(config.game_env);
+  cachedSC = getServerConfig(bootstrapGameEnv);
   return cachedSC;
 }
 export function getServerConfigFromServer(): ServerConfig {
@@ -63,3 +66,7 @@ export function getServerConfig(gameEnv: string) {
       throw Error(`unsupported server configuration: ${gameEnv}`);
   }
 }
+
+export function clearCachedServerConfig(): void {
+  cachedSC = null;
+}
diff --git a/src/core/game/BinaryLoaderGameMapLoader.ts b/src/core/game/BinaryLoaderGameMapLoader.ts
index ff1c5207d..fce7522d7 100644
--- a/src/core/game/BinaryLoaderGameMapLoader.ts
+++ b/src/core/game/BinaryLoaderGameMapLoader.ts
@@ -1,3 +1,4 @@
+import { assetUrl } from "../AssetUrls";
 import { GameMapType } from "./Game";
 import { GameMapLoader, MapData } from "./GameMapLoader";
 import { MapManifest } from "./TerrainMapLoader";
@@ -36,25 +37,25 @@ export class BinaryLoaderGameMapLoader implements GameMapLoader {
         })
         .then((buf) => new Uint8Array(buf));
 
-    const mapBasePath = `/maps/${fileName}`;
+    const mapAssetUrl = (path: string) => assetUrl(`maps/${fileName}/${path}`);
 
     const mapData = {
-      mapBin: this.createLazyLoader(() => loadBinary(`${mapBasePath}/map.bin`)),
+      mapBin: this.createLazyLoader(() => loadBinary(mapAssetUrl("map.bin"))),
       map4xBin: this.createLazyLoader(() =>
-        loadBinary(`${mapBasePath}/map4x.bin`),
+        loadBinary(mapAssetUrl("map4x.bin")),
       ),
       map16xBin: this.createLazyLoader(() =>
-        loadBinary(`${mapBasePath}/map16x.bin`),
+        loadBinary(mapAssetUrl("map16x.bin")),
       ),
       manifest: this.createLazyLoader(() =>
-        fetch(`${mapBasePath}/manifest.json`).then((res) => {
+        fetch(mapAssetUrl("manifest.json")).then((res) => {
           if (!res.ok) {
-            throw new Error(`Failed to load ${mapBasePath}/manifest.json`);
+            throw new Error(`Failed to load ${mapAssetUrl("manifest.json")}`);
           }
           return res.json() as Promise<MapManifest>;
         }),
       ),
-      webpPath: `${mapBasePath}/thumbnail.webp`,
+      webpPath: mapAssetUrl("thumbnail.webp"),
     } satisfies MapData;
 
     this.maps.set(map, mapData);
diff --git a/src/core/game/FetchGameMapLoader.ts b/src/core/game/FetchGameMapLoader.ts
index e517172d5..f7b0e575e 100644
--- a/src/core/game/FetchGameMapLoader.ts
+++ b/src/core/game/FetchGameMapLoader.ts
@@ -5,8 +5,7 @@ export class FetchGameMapLoader implements GameMapLoader {
   private maps: Map<GameMapType, MapData>;
 
   public constructor(
-    private readonly prefix: string,
-    private readonly cacheBuster?: string,
+    private readonly pathResolver: string | ((path: string) => string),
   ) {
     this.maps = new Map<GameMapType, MapData>();
   }
@@ -38,16 +37,15 @@ export class FetchGameMapLoader implements GameMapLoader {
     return mapData;
   }
 
-  private url(map: string, path: string) {
-    let url = `${this.prefix}/${map}/${path}`;
-
-    if (this.cacheBuster) {
-      url += `${url.includes("?") ? "&" : "?"}v=${encodeURIComponent(
-        this.cacheBuster.trim(),
-      )}`;
+  private resolveUrl(path: string): string {
+    if (typeof this.pathResolver === "function") {
+      return this.pathResolver(path);
     }
+    return `${this.pathResolver}/${path}`;
+  }
 
-    return url;
+  private url(map: string, path: string) {
+    return this.resolveUrl(`${map}/${path}`);
   }
 
   private async loadBinaryFromUrl(url: string) {
diff --git a/src/core/worker/Worker.worker.ts b/src/core/worker/Worker.worker.ts
index 9bddea301..65e33c6de 100644
--- a/src/core/worker/Worker.worker.ts
+++ b/src/core/worker/Worker.worker.ts
@@ -1,4 +1,4 @@
-import version from "resources/version.txt?raw";
+import { assetUrl } from "../AssetUrls";
 import { createGameRunner, GameRunner } from "../GameRunner";
 import { FetchGameMapLoader } from "../game/FetchGameMapLoader";
 import { ErrorUpdate, GameUpdateViewData } from "../game/GameUpdates";
@@ -15,8 +15,9 @@ import {
 } from "./WorkerMessages";
 
 const ctx: Worker = self as any;
+globalThis.__ASSET_MANIFEST__ = __ASSET_MANIFEST__;
 let gameRunner: Promise<GameRunner> | null = null;
-const mapLoader = new FetchGameMapLoader(`/maps`, version);
+const mapLoader = new FetchGameMapLoader((path) => assetUrl(`maps/${path}`));
 // Yield threshold; not a backlog cap. Used to avoid monopolizing the worker task
 // and flooding the main thread with messages during catch-up.
 const MAX_TICKS_BEFORE_YIELD = 4;
diff --git a/src/server/GamePreviewBuilder.ts b/src/server/GamePreviewBuilder.ts
index 217edefd1..afd188c11 100644
--- a/src/server/GamePreviewBuilder.ts
+++ b/src/server/GamePreviewBuilder.ts
@@ -1,7 +1,9 @@
 import { z } from "zod";
+import { buildAssetUrl } from "../core/AssetUrls";
 import { ClanTagSchema, GameInfo, UsernameSchema } from "../core/Schemas";
 import { formatPlayerDisplayName } from "../core/Util";
 import { GameMode } from "../core/game/Game";
+import { getRuntimeAssetManifest } from "./RuntimeAssetManifest";
 
 export const PlayerInfoSchema = z.object({
   clientID: z.string().optional(),
@@ -131,13 +133,16 @@ export function escapeHtml(value: string): string {
     .replace(/'/g, "&#39;");
 }
 
-export function buildPreview(
+export async function buildPreview(
   gameID: string,
   origin: string,
   workerPath: string,
   lobby: GameInfo | null,
   publicInfo: ExternalGameInfo | null,
-): PreviewMeta {
+): Promise<PreviewMeta> {
+  const assetManifest = await getRuntimeAssetManifest();
+  const buildAbsoluteAssetUrl = (path: string) =>
+    new URL(buildAssetUrl(path, assetManifest), origin).toString();
   const isFinished = !!publicInfo?.info?.end;
   const isPrivate = lobby?.gameConfig?.gameType === "Private";
 
@@ -188,9 +193,12 @@ export function buildPreview(
   const normalizedMap = map ? map.toLowerCase().replace(/[\s.()]+/g, "") : null;
 
   const mapThumbnail = normalizedMap
-    ? `${origin}/maps/${encodeURIComponent(normalizedMap)}/thumbnail.webp`
+    ? buildAbsoluteAssetUrl(
+        `maps/${encodeURIComponent(normalizedMap)}/thumbnail.webp`,
+      )
     : null;
-  const image = mapThumbnail ?? `${origin}/images/GameplayScreenshot.png`;
+  const image =
+    mapThumbnail ?? buildAbsoluteAssetUrl("images/GameplayScreenshot.png");
 
   const gameType = lobby?.gameConfig?.gameType ?? config.gameType;
   const gameTypeLabel = gameType ? ` (${gameType})` : "";
diff --git a/src/server/GamePreviewRoute.ts b/src/server/GamePreviewRoute.ts
index 01837ff19..c9f3dd83c 100644
--- a/src/server/GamePreviewRoute.ts
+++ b/src/server/GamePreviewRoute.ts
@@ -14,7 +14,8 @@ import {
   ExternalGameInfo,
   ExternalGameInfoSchema,
 } from "./GamePreviewBuilder";
-import { renderHtmlContent, setHtmlNoCacheHeaders } from "./RenderHtml";
+import { setNoStoreHeaders } from "./NoStoreHeaders";
+import { getAppShellContent, setHtmlNoCacheHeaders } from "./RenderHtml";
 
 const requestOrigin = (req: Request, config: ServerConfig): string => {
   const protoHeader = (req.headers["x-forwarded-proto"] as string) ?? "";
@@ -96,7 +97,7 @@ export function registerGamePreviewRoute(opts: {
       }
 
       const origin = requestOrigin(req, config);
-      const meta = buildPreview(
+      const meta = await buildPreview(
         gameID,
         origin,
         config.workerPath(gameID),
@@ -122,7 +123,7 @@ export function registerGamePreviewRoute(opts: {
       }
 
       if (filePath) {
-        const html = await renderHtmlContent(filePath);
+        const html = await getAppShellContent(filePath);
         const root = parse(html);
         const head = root.querySelector("head");
         if (head) {
@@ -151,6 +152,7 @@ export function registerGamePreviewRoute(opts: {
       }
 
       // Fallback to JSON if HTML file not found
+      setNoStoreHeaders(res);
       res.setHeader("Content-Type", "application/json");
       return res.send(JSON.stringify(lobby ?? publicInfo, replacer));
     } catch (error) {
diff --git a/src/server/Master.ts b/src/server/Master.ts
index 90b9cf48f..4390f6e0b 100644
--- a/src/server/Master.ts
+++ b/src/server/Master.ts
@@ -10,7 +10,9 @@ import { getServerConfigFromServer } from "../core/configuration/ConfigLoader";
 import { logger } from "./Logger";
 import { MapPlaylist } from "./MapPlaylist";
 import { MasterLobbyService } from "./MasterLobbyService";
-import { renderHtml } from "./RenderHtml";
+import { setNoStoreHeaders } from "./NoStoreHeaders";
+import { renderAppShell } from "./RenderHtml";
+import { applyStaticAssetCacheControl } from "./StaticAssetCache";
 
 const config = getServerConfigFromServer();
 const playlist = new MapPlaylist();
@@ -26,11 +28,14 @@ const __dirname = path.dirname(__filename);
 
 app.use(express.json());
 
-// Middleware to handle HTML files with EJS templating
+// Serve the shared app shell for the root document.
 app.use(async (req, res, next) => {
   if (req.path === "/") {
     try {
-      await renderHtml(res, path.join(__dirname, "../../static/index.html"));
+      await renderAppShell(
+        res,
+        path.join(__dirname, "../../static/index.html"),
+      );
     } catch (error) {
       log.error("Error rendering index.html:", error);
       res.status(500).send("Internal Server Error");
@@ -43,16 +48,11 @@ app.use(async (req, res, next) => {
 app.use(
   express.static(path.join(__dirname, "../../static"), {
     maxAge: "1y", // Set max-age to 1 year for all static assets
-    setHeaders: (res, path) => {
-      // You can conditionally set different cache times based on file types
-      if (path.match(/\.(js|css|svg)$/)) {
-        // JS, CSS, SVG get long cache with immutable
-        res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
-      } else if (path.match(/\.(bin|dat|exe|dll|so|dylib)$/)) {
-        // Binary files also get long cache with immutable
-        res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
-      }
-      // Other file types use the default maxAge setting
+    setHeaders: (res) => {
+      applyStaticAssetCacheControl(
+        res.setHeader.bind(res),
+        res.req.originalUrl,
+      );
     },
   }),
 );
@@ -65,6 +65,11 @@ app.use(
   }),
 );
 
+app.use("/api", (_req, res, next) => {
+  setNoStoreHeaders(res);
+  next();
+});
+
 // Start the master process
 export async function startMaster() {
   if (!cluster.isPrimary) {
@@ -137,14 +142,6 @@ export async function startMaster() {
   });
 }
 
-app.get("/api/env", async (req, res) => {
-  const envConfig = {
-    game_env: process.env.GAME_ENV,
-  };
-  if (!envConfig.game_env) return res.sendStatus(500);
-  res.json(envConfig);
-});
-
 app.get("/api/health", (_req, res) => {
   const ready = lobbyService?.isHealthy() ?? false;
   if (ready) {
@@ -154,11 +151,17 @@ app.get("/api/health", (_req, res) => {
   }
 });
 
+app.get("/api/instance", (_req, res) => {
+  res.json({
+    instanceId: process.env.INSTANCE_ID ?? "undefined",
+  });
+});
+
 // SPA fallback route
 app.get("*", async function (_req, res) {
   try {
     const htmlPath = path.join(__dirname, "../../static/index.html");
-    await renderHtml(res, htmlPath);
+    await renderAppShell(res, htmlPath);
   } catch (error) {
     log.error("Error rendering SPA fallback:", error);
     res.status(500).send("Internal Server Error");
diff --git a/src/server/NoStoreHeaders.ts b/src/server/NoStoreHeaders.ts
new file mode 100644
index 000000000..77996c025
--- /dev/null
+++ b/src/server/NoStoreHeaders.ts
@@ -0,0 +1,10 @@
+import type { Response } from "express";
+
+export function setNoStoreHeaders(res: Response): void {
+  res.setHeader(
+    "Cache-Control",
+    "no-store, no-cache, must-revalidate, proxy-revalidate",
+  );
+  res.setHeader("Pragma", "no-cache");
+  res.setHeader("Expires", "0");
+}
diff --git a/src/server/PublicAssetManifest.ts b/src/server/PublicAssetManifest.ts
new file mode 100644
index 000000000..e46f37e50
--- /dev/null
+++ b/src/server/PublicAssetManifest.ts
@@ -0,0 +1,187 @@
+import { createHash } from "crypto";
+import fs from "fs";
+import { globSync } from "glob";
+import path from "path";
+import {
+  type AssetManifest,
+  buildAssetUrl,
+  encodeAssetPath,
+  normalizeAssetPath,
+} from "../core/AssetUrls";
+
+const HASHED_PUBLIC_ASSET_GLOBS = [
+  "changelog.md",
+  "manifest.json",
+  "cosmetics/**/*",
+  "flags/**/*",
+  "fonts/**/*",
+  "icons/**/*",
+  "images/**/*",
+  "lang/**/*",
+  "maps/**/*",
+  "sounds/**/*",
+  "sprites/**/*",
+] as const;
+
+const ROOT_PUBLIC_FILES = new Set([
+  "LICENSE",
+  "ads.txt",
+  "privacy-policy.html",
+  "robots.txt",
+  "terms-of-service.html",
+  "version.txt",
+]);
+
+const manifestCache = new Map<string, AssetManifest>();
+
+function toPosixPath(filePath: string): string {
+  return filePath.split(path.sep).join(path.posix.sep);
+}
+
+function createContentHash(filePath: string): string {
+  const content = fs.readFileSync(filePath);
+  return createHash("sha256").update(content).digest("hex").slice(0, 12);
+}
+
+function createStringHash(content: string): string {
+  return createHash("sha256").update(content).digest("hex").slice(0, 12);
+}
+
+function createHashedAssetUrl(relativePath: string, hash: string): string {
+  const parsed = path.posix.parse(toPosixPath(relativePath));
+  const hashedFileName = `${parsed.name}.${hash}${parsed.ext}`;
+  const hashedRelativePath = path.posix.join(
+    "_assets",
+    parsed.dir,
+    hashedFileName,
+  );
+  return `/${encodeAssetPath(hashedRelativePath)}`;
+}
+
+function renderWebManifest(
+  resourcesDir: string,
+  assetManifest: AssetManifest,
+): string {
+  const sourcePath = path.join(resourcesDir, "manifest.json");
+  const manifest = JSON.parse(fs.readFileSync(sourcePath, "utf8")) as {
+    icons?: Array<{ src?: string }>;
+  };
+  manifest.icons = manifest.icons?.map((icon) => ({
+    ...icon,
+    src: buildAssetUrl(icon.src ?? "", assetManifest),
+  }));
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+export function getResourcesDir(rootDir: string = process.cwd()): string {
+  return path.join(rootDir, "resources");
+}
+
+export function shouldKeepRootPublicFile(relativePath: string): boolean {
+  return ROOT_PUBLIC_FILES.has(normalizeAssetPath(relativePath));
+}
+
+export function listHashedPublicAssetPaths(resourcesDir: string): string[] {
+  const files = new Set<string>();
+  for (const pattern of HASHED_PUBLIC_ASSET_GLOBS) {
+    for (const file of globSync(pattern, {
+      cwd: resourcesDir,
+      nodir: true,
+      dot: false,
+      posix: true,
+    })) {
+      files.add(normalizeAssetPath(file));
+    }
+  }
+  return [...files].sort();
+}
+
+export function listRootPublicFiles(resourcesDir: string): string[] {
+  return globSync("**/*", {
+    cwd: resourcesDir,
+    nodir: true,
+    dot: false,
+    posix: true,
+  })
+    .map((file) => normalizeAssetPath(file))
+    .filter((file) => shouldKeepRootPublicFile(file))
+    .sort();
+}
+
+export function buildPublicAssetManifest(resourcesDir: string): AssetManifest {
+  const cached = manifestCache.get(resourcesDir);
+  if (cached) {
+    return cached;
+  }
+
+  const manifest: AssetManifest = {};
+  for (const relativePath of listHashedPublicAssetPaths(resourcesDir)) {
+    if (relativePath === "manifest.json") {
+      continue;
+    }
+
+    const absolutePath = path.join(resourcesDir, relativePath);
+    const hash = createContentHash(absolutePath);
+    manifest[relativePath] = createHashedAssetUrl(relativePath, hash);
+  }
+
+  const renderedWebManifest = renderWebManifest(resourcesDir, manifest);
+  manifest["manifest.json"] = createHashedAssetUrl(
+    "manifest.json",
+    createStringHash(renderedWebManifest),
+  );
+
+  manifestCache.set(resourcesDir, manifest);
+  return manifest;
+}
+
+export function clearPublicAssetManifestCache(): void {
+  manifestCache.clear();
+}
+
+export function createHashedPublicAssetFiles(
+  resourcesDir: string,
+  outDir: string,
+  assetManifest: AssetManifest,
+): void {
+  for (const [relativePath, hashedUrl] of Object.entries(assetManifest)) {
+    const sourcePath = path.join(resourcesDir, relativePath);
+    const outputPath = path.join(outDir, normalizeAssetPath(hashedUrl));
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+
+    if (relativePath === "manifest.json") {
+      fs.writeFileSync(
+        outputPath,
+        renderWebManifest(resourcesDir, assetManifest),
+      );
+      continue;
+    }
+
+    fs.copyFileSync(sourcePath, outputPath);
+  }
+}
+
+export function copyRootPublicFiles(
+  resourcesDir: string,
+  outDir: string,
+): void {
+  for (const relativePath of listRootPublicFiles(resourcesDir)) {
+    const sourcePath = path.join(resourcesDir, relativePath);
+    const outputPath = path.join(outDir, relativePath);
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.copyFileSync(sourcePath, outputPath);
+  }
+}
+
+export function writePublicAssetManifestModule(
+  outDir: string,
+  assetManifest: AssetManifest,
+): void {
+  const manifestPath = path.join(outDir, "_assets", "asset-manifest.mjs");
+  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+  const serializedManifest = JSON.stringify(assetManifest, null, 2);
+  fs.writeFileSync(
+    manifestPath,
+    `const assetManifest = ${serializedManifest};\nexport { assetManifest };\nexport default assetManifest;\n`,
+  );
+}
diff --git a/src/server/RenderHtml.ts b/src/server/RenderHtml.ts
index 220897a71..f7898f3da 100644
--- a/src/server/RenderHtml.ts
+++ b/src/server/RenderHtml.ts
@@ -1,31 +1,66 @@
 import ejs from "ejs";
 import type { Response } from "express";
 import fs from "fs/promises";
+import { buildAssetUrl } from "../core/AssetUrls";
+import { setNoStoreHeaders } from "./NoStoreHeaders";
+import { getRuntimeAssetManifest } from "./RuntimeAssetManifest";
+
+const APP_SHELL_CACHE_CONTROL =
+  "public, max-age=0, s-maxage=300, stale-while-revalidate=86400";
+
+const appShellContentCache = new Map<string, Promise<string>>();
 
 export async function renderHtmlContent(htmlPath: string): Promise<string> {
   const htmlContent = await fs.readFile(htmlPath, "utf-8");
+  const assetManifest = await getRuntimeAssetManifest();
   return ejs.render(htmlContent, {
     gitCommit: JSON.stringify(process.env.GIT_COMMIT ?? "undefined"),
-    instanceId: JSON.stringify(process.env.INSTANCE_ID ?? "undefined"),
+    assetManifest: JSON.stringify(assetManifest),
+    gameEnv: JSON.stringify(process.env.GAME_ENV ?? "dev"),
+    manifestHref: buildAssetUrl("manifest.json", assetManifest),
+    faviconHref: buildAssetUrl("images/Favicon.svg", assetManifest),
+    gameplayScreenshotUrl: buildAssetUrl(
+      "images/GameplayScreenshot.png",
+      assetManifest,
+    ),
+    backgroundImageUrl: buildAssetUrl("images/background.webp", assetManifest),
+    desktopLogoImageUrl: buildAssetUrl("images/OpenFront.webp", assetManifest),
+    mobileLogoImageUrl: buildAssetUrl("images/OF.webp", assetManifest),
   });
 }
 
+export async function getAppShellContent(htmlPath: string): Promise<string> {
+  let cachedContent = appShellContentCache.get(htmlPath);
+  if (!cachedContent) {
+    cachedContent = renderHtmlContent(htmlPath).catch((error: unknown) => {
+      appShellContentCache.delete(htmlPath);
+      throw error;
+    });
+    appShellContentCache.set(htmlPath, cachedContent);
+  }
+  return cachedContent;
+}
+
+export function clearAppShellContentCache(): void {
+  appShellContentCache.clear();
+}
+
+export function setAppShellCacheHeaders(res: Response): void {
+  res.setHeader("Cache-Control", APP_SHELL_CACHE_CONTROL);
+  res.setHeader("Content-Type", "text/html");
+}
+
 export function setHtmlNoCacheHeaders(res: Response): void {
-  res.setHeader(
-    "Cache-Control",
-    "no-store, no-cache, must-revalidate, proxy-revalidate",
-  );
-  res.setHeader("Pragma", "no-cache");
-  res.setHeader("Expires", "0");
+  setNoStoreHeaders(res);
   res.setHeader("ETag", "");
   res.setHeader("Content-Type", "text/html");
 }
 
-export async function renderHtml(
+export async function renderAppShell(
   res: Response,
   htmlPath: string,
 ): Promise<void> {
-  const rendered = await renderHtmlContent(htmlPath);
-  setHtmlNoCacheHeaders(res);
+  const rendered = await getAppShellContent(htmlPath);
+  setAppShellCacheHeaders(res);
   res.send(rendered);
 }
diff --git a/src/server/RuntimeAssetManifest.ts b/src/server/RuntimeAssetManifest.ts
new file mode 100644
index 000000000..24fdeed7a
--- /dev/null
+++ b/src/server/RuntimeAssetManifest.ts
@@ -0,0 +1,40 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+import type { AssetManifest } from "../core/AssetUrls";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const staticDir = path.join(__dirname, "../../static");
+const manifestPath = path.join(staticDir, "_assets", "asset-manifest.mjs");
+
+let manifestPromise: Promise<AssetManifest> | null = null;
+let manifestVersion = 0;
+
+async function importRuntimeAssetManifest(
+  version: number,
+): Promise<AssetManifest> {
+  const manifestModule = (await import(
+    `${pathToFileURL(manifestPath).href}?v=${version}`
+  )) as {
+    assetManifest?: AssetManifest;
+    default?: AssetManifest;
+  };
+  return manifestModule.assetManifest ?? manifestModule.default ?? {};
+}
+
+export async function getRuntimeAssetManifest(): Promise<AssetManifest> {
+  if (!fs.existsSync(manifestPath)) {
+    return {};
+  }
+
+  manifestPromise ??= importRuntimeAssetManifest(manifestVersion).catch(
+    () => ({}),
+  );
+  return manifestPromise;
+}
+
+export function clearRuntimeAssetManifestCache(): void {
+  manifestVersion++;
+  manifestPromise = null;
+}
diff --git a/src/server/StaticAssetCache.ts b/src/server/StaticAssetCache.ts
new file mode 100644
index 000000000..abf3d50b7
--- /dev/null
+++ b/src/server/StaticAssetCache.ts
@@ -0,0 +1,33 @@
+const IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
+
+function stripQueryString(urlPath: string): string {
+  return urlPath.split("?", 1)[0];
+}
+
+export function getStaticAssetCacheControl(
+  urlPath: string | undefined,
+): string | undefined {
+  if (!urlPath) {
+    return undefined;
+  }
+
+  const normalizedPath = stripQueryString(urlPath);
+  if (
+    normalizedPath.startsWith("/assets/") ||
+    normalizedPath.startsWith("/_assets/")
+  ) {
+    return IMMUTABLE_CACHE_CONTROL;
+  }
+
+  return undefined;
+}
+
+export function applyStaticAssetCacheControl(
+  setHeader: (name: string, value: string) => void,
+  urlPath: string | undefined,
+): void {
+  const cacheControl = getStaticAssetCacheControl(urlPath);
+  if (cacheControl) {
+    setHeader("Cache-Control", cacheControl);
+  }
+}
diff --git a/src/server/Worker.ts b/src/server/Worker.ts
index e0a16d3b6..98e1aa3e2 100644
--- a/src/server/Worker.ts
+++ b/src/server/Worker.ts
@@ -27,8 +27,10 @@ import { logger } from "./Logger";
 
 import { GameEnv } from "../core/configuration/Config";
 import { MapPlaylist } from "./MapPlaylist";
+import { setNoStoreHeaders } from "./NoStoreHeaders";
 import { startPolling } from "./PollingLoop";
 import { PrivilegeRefresher } from "./PrivilegeRefresher";
+import { applyStaticAssetCacheControl } from "./StaticAssetCache";
 import { verifyTurnstileToken } from "./Turnstile";
 import { WorkerLobbyService } from "./WorkerLobbyService";
 import { initWorkerMetrics } from "./WorkerMetrics";
@@ -110,7 +112,16 @@ export async function startWorker() {
   // Configure MIME types for webp files
   express.static.mime.define({ "image/webp": ["webp"] });
 
-  app.use(express.static(path.join(__dirname, "../../out")));
+  app.use(
+    express.static(path.join(__dirname, "../../out"), {
+      setHeaders: (res) => {
+        applyStaticAssetCacheControl(
+          res.setHeader.bind(res),
+          res.req.originalUrl,
+        );
+      },
+    }),
+  );
   app.use(
     "/maps",
     express.static(path.join(__dirname, "../../static/maps"), {
@@ -129,6 +140,11 @@ export async function startWorker() {
     }),
   );
 
+  app.use("/api", (_req, res, next) => {
+    setNoStoreHeaders(res);
+    next();
+  });
+
   app.post("/api/create_game/:id", async (req, res) => {
     const id = req.params.id;
 
diff --git a/tests/AssetUrls.test.ts b/tests/AssetUrls.test.ts
new file mode 100644
index 000000000..a48876e1b
--- /dev/null
+++ b/tests/AssetUrls.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, test } from "vitest";
+import { buildAssetUrl } from "../src/core/AssetUrls";
+
+describe("AssetUrls", () => {
+  test("returns hashed URLs for direct asset matches", () => {
+    expect(
+      buildAssetUrl("images/Favicon.svg", {
+        "images/Favicon.svg": "/_assets/images/Favicon.hash.svg",
+      }),
+    ).toBe("/_assets/images/Favicon.hash.svg");
+  });
+
+  test("maps directory prefixes into the hashed asset namespace", () => {
+    const manifest = {
+      "maps/britanniaclassic/manifest.json":
+        "/_assets/maps/britanniaclassic/manifest.hash.json",
+      "maps/britanniaclassic/map.bin":
+        "/_assets/maps/britanniaclassic/map.hash.bin",
+    };
+
+    expect(buildAssetUrl("maps", manifest)).toBe("/_assets/maps");
+    expect(buildAssetUrl("maps/britanniaclassic", manifest)).toBe(
+      "/_assets/maps/britanniaclassic",
+    );
+  });
+
+  test("falls back to the unversioned path when manifest has no match", () => {
+    expect(buildAssetUrl("images/unknown.svg", {})).toBe("/images/unknown.svg");
+  });
+
+  test("rejects dot segments in asset paths", () => {
+    expect(() => buildAssetUrl("../api/instance", {})).toThrow(
+      "Invalid asset path segment: ..",
+    );
+    expect(() => buildAssetUrl("images/%2e%2e/secret.svg", {})).toThrow(
+      "Invalid asset path segment: %2e%2e",
+    );
+  });
+
+  test("rejects empty asset paths", () => {
+    expect(() => buildAssetUrl("", {})).toThrow("Asset path must not be empty");
+    expect(() => buildAssetUrl("///", {})).toThrow(
+      "Asset path must not be empty",
+    );
+  });
+});
diff --git a/tests/core/configuration/ConfigLoader.test.ts b/tests/core/configuration/ConfigLoader.test.ts
new file mode 100644
index 000000000..65fd81757
--- /dev/null
+++ b/tests/core/configuration/ConfigLoader.test.ts
@@ -0,0 +1,24 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { GameEnv } from "../../../src/core/configuration/Config";
+import {
+  clearCachedServerConfig,
+  getServerConfigFromClient,
+} from "../../../src/core/configuration/ConfigLoader";
+
+describe("ConfigLoader", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    window.BOOTSTRAP_CONFIG = undefined;
+    clearCachedServerConfig();
+  });
+
+  test("uses bootstrap config without fetching /api/env", async () => {
+    window.BOOTSTRAP_CONFIG = { gameEnv: "prod" };
+    const fetchSpy = vi.spyOn(globalThis, "fetch");
+
+    const config = await getServerConfigFromClient();
+
+    expect(config.env()).toBe(GameEnv.Prod);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});
diff --git a/tests/core/game/FetchGameMapLoader.test.ts b/tests/core/game/FetchGameMapLoader.test.ts
new file mode 100644
index 000000000..d4e9d8319
--- /dev/null
+++ b/tests/core/game/FetchGameMapLoader.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, test, vi } from "vitest";
+import { FetchGameMapLoader } from "../../../src/core/game/FetchGameMapLoader";
+import { GameMapType } from "../../../src/core/game/Game";
+
+describe("FetchGameMapLoader", () => {
+  test("resolves each map file through the provided path resolver", async () => {
+    const fetchMock = vi.fn(async (url: string) => ({
+      ok: true,
+      arrayBuffer: async () => new ArrayBuffer(0),
+      json: async () => ({ url }),
+      statusText: "OK",
+    }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    const loader = new FetchGameMapLoader(
+      (path) => `/_assets/maps/${path}.hashed`,
+    );
+    const mapData = loader.getMapData(GameMapType.BritanniaClassic);
+
+    expect(mapData.webpPath).toBe(
+      "/_assets/maps/britanniaclassic/thumbnail.webp.hashed",
+    );
+
+    await mapData.manifest();
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      "/_assets/maps/britanniaclassic/manifest.json.hashed",
+    );
+  });
+});
diff --git a/tests/server/NoStoreHeaders.test.ts b/tests/server/NoStoreHeaders.test.ts
new file mode 100644
index 000000000..a25234e16
--- /dev/null
+++ b/tests/server/NoStoreHeaders.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, test } from "vitest";
+import { setNoStoreHeaders } from "../../src/server/NoStoreHeaders";
+
+describe("NoStoreHeaders", () => {
+  test("sets explicit no-store headers", () => {
+    const headers = new Map<string, string>();
+    const response = {
+      setHeader(name: string, value: string) {
+        headers.set(name, value);
+      },
+    } as any;
+
+    setNoStoreHeaders(response);
+
+    expect(headers.get("Cache-Control")).toBe(
+      "no-store, no-cache, must-revalidate, proxy-revalidate",
+    );
+    expect(headers.get("Pragma")).toBe("no-cache");
+    expect(headers.get("Expires")).toBe("0");
+  });
+});
diff --git a/tests/server/PublicAssetManifest.test.ts b/tests/server/PublicAssetManifest.test.ts
new file mode 100644
index 000000000..60bd46b7d
--- /dev/null
+++ b/tests/server/PublicAssetManifest.test.ts
@@ -0,0 +1,71 @@
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+import { afterEach, describe, expect, test } from "vitest";
+import {
+  buildPublicAssetManifest,
+  clearPublicAssetManifestCache,
+  createHashedPublicAssetFiles,
+} from "../../src/server/PublicAssetManifest";
+
+describe("PublicAssetManifest", () => {
+  let tempDir: string | null = null;
+
+  afterEach(async () => {
+    clearPublicAssetManifestCache();
+    if (tempDir) {
+      await fs.rm(tempDir, { recursive: true, force: true });
+      tempDir = null;
+    }
+  });
+
+  test("hashes manifest.json from its rewritten content", async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "public-assets-"));
+    const resourcesDir = path.join(tempDir, "resources");
+    const outDir = path.join(tempDir, "static");
+
+    await fs.mkdir(path.join(resourcesDir, "icons"), { recursive: true });
+    await fs.writeFile(
+      path.join(resourcesDir, "manifest.json"),
+      JSON.stringify(
+        {
+          name: "OpenFront",
+          icons: [{ src: "icons/app-icon.png" }],
+        },
+        null,
+        2,
+      ),
+    );
+    await fs.writeFile(
+      path.join(resourcesDir, "icons", "app-icon.png"),
+      "icon-v1",
+      "utf8",
+    );
+
+    const firstManifest = buildPublicAssetManifest(resourcesDir);
+    const firstManifestHref = firstManifest["manifest.json"];
+    const firstIconHref = firstManifest["icons/app-icon.png"];
+
+    createHashedPublicAssetFiles(resourcesDir, outDir, firstManifest);
+    const firstOutput = await fs.readFile(
+      path.join(outDir, firstManifestHref.slice(1)),
+      "utf8",
+    );
+
+    await fs.writeFile(
+      path.join(resourcesDir, "icons", "app-icon.png"),
+      "icon-v2",
+      "utf8",
+    );
+    clearPublicAssetManifestCache();
+
+    const secondManifest = buildPublicAssetManifest(resourcesDir);
+    const secondManifestHref = secondManifest["manifest.json"];
+    const secondIconHref = secondManifest["icons/app-icon.png"];
+
+    expect(firstIconHref).not.toBe(secondIconHref);
+    expect(firstManifestHref).not.toBe(secondManifestHref);
+    expect(firstOutput).toContain(firstIconHref);
+    expect(firstOutput).not.toContain(secondIconHref);
+  });
+});
diff --git a/tests/server/RenderHtml.test.ts b/tests/server/RenderHtml.test.ts
new file mode 100644
index 000000000..d4f600f2c
--- /dev/null
+++ b/tests/server/RenderHtml.test.ts
@@ -0,0 +1,60 @@
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+import { afterEach, describe, expect, test } from "vitest";
+import {
+  clearAppShellContentCache,
+  getAppShellContent,
+  setAppShellCacheHeaders,
+} from "../../src/server/RenderHtml";
+
+describe("RenderHtml", () => {
+  const originalGitCommit = process.env.GIT_COMMIT;
+  let tempDir: string | null = null;
+
+  afterEach(async () => {
+    process.env.GIT_COMMIT = originalGitCommit;
+    clearAppShellContentCache();
+
+    if (tempDir) {
+      await fs.rm(tempDir, { recursive: true, force: true });
+      tempDir = null;
+    }
+  });
+
+  test("reuses cached app shell content", async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "render-html-"));
+    const htmlPath = path.join(tempDir, "index.html");
+    await fs.writeFile(
+      htmlPath,
+      "<script>window.GIT_COMMIT = <%- gitCommit %>;</script>",
+      "utf8",
+    );
+
+    process.env.GIT_COMMIT = "first";
+    const first = await getAppShellContent(htmlPath);
+
+    process.env.GIT_COMMIT = "second";
+    const second = await getAppShellContent(htmlPath);
+
+    expect(first).toContain('"first"');
+    expect(second).toBe(first);
+    expect(second).not.toContain('"second"');
+  });
+
+  test("sets shared-cache headers for the app shell", () => {
+    const headers = new Map<string, string>();
+    const response = {
+      setHeader(name: string, value: string) {
+        headers.set(name, value);
+      },
+    } as any;
+
+    setAppShellCacheHeaders(response);
+
+    expect(headers.get("Cache-Control")).toBe(
+      "public, max-age=0, s-maxage=300, stale-while-revalidate=86400",
+    );
+    expect(headers.get("Content-Type")).toBe("text/html");
+  });
+});
diff --git a/tests/server/StaticAssetCache.test.ts b/tests/server/StaticAssetCache.test.ts
new file mode 100644
index 000000000..6c92e63ac
--- /dev/null
+++ b/tests/server/StaticAssetCache.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, test } from "vitest";
+import { getStaticAssetCacheControl } from "../../src/server/StaticAssetCache";
+
+describe("StaticAssetCache", () => {
+  test("marks Vite asset namespace as immutable", () => {
+    expect(getStaticAssetCacheControl("/assets/index-abc123.js")).toBe(
+      "public, max-age=31536000, immutable",
+    );
+  });
+
+  test("marks custom hashed asset namespace as immutable", () => {
+    expect(
+      getStaticAssetCacheControl("/_assets/maps/world/manifest.hash.json"),
+    ).toBe("public, max-age=31536000, immutable");
+  });
+
+  test("does not mark other paths as immutable", () => {
+    expect(getStaticAssetCacheControl("/manifest.json")).toBeUndefined();
+    expect(getStaticAssetCacheControl("/api/health")).toBeUndefined();
+  });
+});
diff --git a/vite.config.ts b/vite.config.ts
index 4b7af9f86..e53544896 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -5,6 +5,14 @@ import { defineConfig, loadEnv } from "vite";
 import { createHtmlPlugin } from "vite-plugin-html";
 import { viteStaticCopy } from "vite-plugin-static-copy";
 import tsconfigPaths from "vite-tsconfig-paths";
+import { type AssetManifest, buildAssetUrl } from "./src/core/AssetUrls";
+import {
+  buildPublicAssetManifest,
+  copyRootPublicFiles,
+  createHashedPublicAssetFiles,
+  getResourcesDir,
+  writePublicAssetManifestModule,
+} from "./src/server/PublicAssetManifest";
 
 // Vite already handles these, but its good practice to define them explicitly
 const __filename = fileURLToPath(import.meta.url);
@@ -13,6 +21,35 @@ const __dirname = path.dirname(__filename);
 export default defineConfig(({ mode }) => {
   const env = loadEnv(mode, process.cwd(), "");
   const isProduction = mode === "production";
+  const resourcesDir = getResourcesDir(__dirname);
+  const assetManifest: AssetManifest = isProduction
+    ? buildPublicAssetManifest(resourcesDir)
+    : {};
+  const htmlAssetData = {
+    assetManifest: JSON.stringify(assetManifest),
+    gameEnv: JSON.stringify(env.GAME_ENV ?? "dev"),
+    manifestHref: buildAssetUrl("manifest.json", assetManifest),
+    faviconHref: buildAssetUrl("images/Favicon.svg", assetManifest),
+    gameplayScreenshotUrl: buildAssetUrl(
+      "images/GameplayScreenshot.png",
+      assetManifest,
+    ),
+    backgroundImageUrl: buildAssetUrl("images/background.webp", assetManifest),
+    desktopLogoImageUrl: buildAssetUrl("images/OpenFront.webp", assetManifest),
+    mobileLogoImageUrl: buildAssetUrl("images/OF.webp", assetManifest),
+  };
+
+  const syncHashedPublicAssets = () => ({
+    name: "sync-hashed-public-assets",
+    apply: "build" as const,
+    closeBundle() {
+      const outDir = path.join(__dirname, "static");
+      copyRootPublicFiles(resourcesDir, outDir);
+      writePublicAssetManifestModule(outDir, assetManifest);
+      createHashedPublicAssetFiles(resourcesDir, outDir, assetManifest);
+    },
+  });
+
   // In dev, redirect visits to /w*/game/* to "/" so Vite serves the index.html.
   const devGameHtmlBypass = (req?: {
     url?: string;
@@ -40,7 +77,7 @@ export default defineConfig(({ mode }) => {
     },
     root: "./",
     base: "/",
-    publicDir: "resources", // Access static assets via import or explicit copy
+    publicDir: isProduction ? false : "resources",
 
     resolve: {
       alias: {
@@ -64,7 +101,7 @@ export default defineConfig(({ mode }) => {
               inject: {
                 data: {
                   gitCommit: JSON.stringify("DEV"),
-                  instanceId: JSON.stringify("DEV_ID"),
+                  ...htmlAssetData,
                 },
               },
             }),
@@ -77,10 +114,12 @@ export default defineConfig(({ mode }) => {
           },
         ],
       }),
+      ...(isProduction ? [syncHashedPublicAssets()] : []),
       tailwindcss(),
     ],
 
     define: {
+      __ASSET_MANIFEST__: JSON.stringify(assetManifest),
       "process.env.WEBSOCKET_URL": JSON.stringify(
         isProduction ? "" : "localhost:3000",
       ),