Evan
b72956d0c0
## Problem After the WebGL2 renderer migration, a small number of users (~a dozen of 100k DAU) report ~5fps. Root cause: they run WebGL **without GPU acceleration** (hardware acceleration disabled, blocklisted driver, or a locked-down machine), so they get a SwiftShader/software context. Software-rendered WebGL is hopeless for a real-time game — ~1fps locally. We are not supporting a canvas2d fallback. Instead: demand a GPU-accelerated context, and if we can't get one, **gate** the user with actionable instructions rather than letting the game crawl. ## What this does - **`initGL()`** ([initGL.ts](../blob/webgl-software-render-gate/src/client/render/gl/initGL.ts)) — demands `failIfMajorPerformanceCaveat: true` **and** inspects the unmasked renderer string. The flag alone isn't enough: when hardware acceleration is turned off in browser *settings* (vs. a blocklisted driver), Chrome still hands back a SwiftShader context, so we'd otherwise run at 1fps. Classifies the outcome as `ok` / `software` / `unsupported`. - **`GPURenderer`** throws `GLUnavailableError` on a non-accelerated context; the game-start `catch` shows the gate and removes the orphaned canvas. - **`<webgl-gate>`** Lit component renders a full-screen blocking gate with per-browser steps (Chrome / Edge / Firefox / Safari) for enabling hardware acceleration / WebGL. - **`gl_init` analytics event** fires every session (`status` + `renderer` for non-ok) via the existing Google Tag, so we can size the real affected % within a day. ## Notes / decisions - The gate copy is **intentionally inlined (not translated)** — it's a rarely-seen, browser-specific troubleshooting screen; 28 Crowdin keys would be poor cost/benefit, and a non-English user still has to navigate English browser menus. - `showGLGate` lazy-loads the component (`import()`), so the `render/gl` module that `Renderer.ts` imports doesn't statically pull a UI component into its graph. ## Update: fingerprint-capped contexts (#4357) A third failure class, integrated after the initial PR: `privacy.resistFingerprinting` (default-on in LibreWolf and Mullvad Browser, opt-in in Firefox) caps `MAX_TEXTURE_SIZE` at 2048 on an otherwise hardware-accelerated context. The renderer unconditionally allocates a 4096-wide palette texture, so the oversized `texImage2D` calls fail silently and the whole map renders **black** (#4357). - `initGL` now reads `MAX_TEXTURE_SIZE` after the software check and classifies the context as **`limited`** when it's below `getPaletteSize()` (4096 — the hard floor every game needs). - Unlike `software`/`unsupported`, **`limited` is a warning, not a hard block**: `initGL` still returns the context, the game starts normally, and the gate is shown with a "Continue anyway" button. `GPURenderer` exposes the capped renderer/size via `glLimited` (surfaced through `MapRenderer`), which `ClientGameRunner` uses to show the warning and log analytics. - The gate shows fingerprinting-specific instructions for `limited` (add the site to `privacy.resistFingerprinting.exemptedDomains` in `about:config`) instead of the hardware-acceleration steps. - `gl_init` reports `max_texture_size` alongside the renderer for this status, so we can size the RFP-affected population too. Fixes #4357 ## Test plan - [x] Unit tests for `initGL`'s `ok` / `software` / `unsupported` branching, incl. the "returns a context but renderer is software" case (`tests/client/initGL.test.ts`). - [x] lint / prettier / tsc clean. - [x] **Verified in real browsers (macOS).** All three gate states reproduced: - `software`: Chrome with `--use-gl=angle --use-angle=swiftshader` (confirmed "Software only" at `chrome://gpu`), and Chrome with hardware acceleration toggled off in settings — both show the hard gate instead of a 1fps game. - `unsupported`: Firefox with `webgl.disabled=true` shows the unsupported gate. - `limited`: Firefox with `privacy.resistFingerprinting=true` (MAX_TEXTURE_SIZE capped to 2048, same as LibreWolf's default) shows the dismissible warning; "Continue anyway" starts the game, and exempting the site via `privacy.resistFingerprinting.exemptedDomains` removes the warning. ## Acceptance criteria - Accelerated users: unchanged. - Software / no-accel users: see the enable-acceleration gate, not a 1fps game. - No-WebGL2 users: see the unsupported gate. - `gl_init` fires every session with status (+ renderer for non-ok). 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
OpenFront.io is an online real-time strategy game focused on territorial control and alliance building. Players compete to expand their territory, build structures, and form strategic alliances in various maps based on real-world geography.
This is a fork/rewrite of WarFront.io. Credit to https://github.com/WarFrontIO.
License
OpenFront source code is licensed under the GNU Affero General Public License v3.0
Current copyright notices appear in:
- Footer: "© OpenFront and Contributors"
- Loading screen: "© OpenFront and Contributors"
Modified versions must preserve these notices in reasonably visible locations.
See the LICENSE for complete requirements.
For asset licensing, see LICENSE-ASSETS.
For license history, see LICENSING.md.
🌟 Features
- Real-time Strategy Gameplay: Expand your territory and engage in strategic battles
- Alliance System: Form alliances with other players for mutual defense
- Multiple Maps: Play across various geographical regions including Europe, Asia, Africa, and more
- Resource Management: Balance your expansion with defensive capabilities
- Cross-platform: Play in any modern web browser
📋 Prerequisites
- npm (v10.9.2 or higher)
- A modern web browser (Chrome, Firefox, Edge, etc.)
🚀 Installation
-
Clone the repository
git clone https://github.com/openfrontio/OpenFrontIO.git cd OpenFrontIO -
Install dependencies
npm run instDo NOT use
npm installnornpm ibut instead use ournpm run inst. It runs the safernpm ci --ignore-scriptsto install dependencies exactly according to the versions inpackage-lock.jsonand doesn't run scripts. This can prevent being hit by a supply chain attack.
🎮 Running the Game
Development Mode
Run both the client and server in development mode with live reloading:
npm run dev
This will:
- Start the webpack dev server for the client
- Launch the game server with development settings
- Open the game in your default browser (to disable this behavior, set
SKIP_BROWSER_OPEN=truein your environment)
Client Only
To run just the client with hot reloading:
npm run start:client
Server Only
To run just the server with development settings:
npm run start:server-dev
Connecting to staging or production backends
Sometimes it's useful to connect to production servers when replaying a game, testing user profiles, purchases, or login flow.
To replay a production game, make sure you're on the same commit that the game you want to replay was executed on, you can find the
gitCommitvalue viahttps://api.openfront.io/game/[gameId]. Unfinished games cannot be replayed on localhost.
To connect to staging api servers:
npm run dev:staging
To connect to production api servers:
npm run dev:prod
🛠️ Development Tools
-
Format code:
npm run format -
Lint code:
npm run lint -
Lint and fix code:
npm run lint:fix -
Testing
npm test
🏗️ Project Structure
/src/client- Frontend game client/src/core- Deterministic game simulation/src/server- Backend game server/resources- Static assets (images, maps, etc.)
🤝 Contributing
Contributions and translations are welcome! See CONTRIBUTING.md for the workflow, the approved-issue process, project governance, and translation info.