Skip to content

Update web port plan to support dual WebGL2 + WebGPU renderer #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ConstCorrectness merged 2 commits into from
Feb 19, 2026
Merged

Update web port plan to support dual WebGL2 + WebGPU renderer #2

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b66b5d1
Update web port plan for dual WebGL2 and WebGPU backends
ConstCorrectness Feb 19, 2026
cff4427
Merge branch 'master' into codex/replicate-in-webgl
ConstCorrectness Feb 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
178 changes: 160 additions & 18 deletions docs/web_port_plan.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This document outlines a **full web-native port** strategy for AssaultCube with:

- Rendering: **WebGL2**
- Rendering: **WebGL2** and **WebGPU** (dual-backend track)
- Networking: **WebSockets** (gameplay + control plane)
- Voice chat: **WebRTC audio**
- Transport: **No ENet dependency** in the browser client
Expand All @@ -12,7 +12,7 @@ This document outlines a **full web-native port** strategy for AssaultCube with:
### 1.1 Client Runtime (Browser)
- WASM module for core simulation/gameplay logic.
- JavaScript/TypeScript host for platform integrations:
- WebGL2 rendering backend
- Dual rendering backends (WebGL2 + WebGPU) behind a shared renderer interface
- Input (pointer lock, keyboard, gamepad)
- Asset loading / persistence
- WebSocket connection manager
Expand Down Expand Up @@ -80,25 +80,48 @@ Reuse existing WebSocket channel for WebRTC signaling:
- Push-to-talk, mute self, mute remote.
- Server-side role checks for room moderation commands.

## 4) Rendering Migration (WebGL2)
## 4) Rendering Migration (WebGL2 + WebGPU)

### 4.1 Core Changes
- Remove fixed-function/immediate mode assumptions.
- Introduce render abstraction:
- static world geometry
- skinned/animated meshes
- particles
- HUD/2D overlays
### 4.1 Renderer Strategy
- Build a **single renderer API** with two interchangeable backends:
- **WebGL2 backend** for broad browser/hardware compatibility and stable fallback.
- **WebGPU backend** for modern pipeline features and better long-term performance ceiling.
- Keep gameplay and scene code backend-agnostic (`RenderDevice`, `CommandList`, `Material`, `MeshHandle`).

### 4.2 Shader and Material System
- Material definition -> shader variant mapping.
- Texture atlas and sampler state registry.
- Uniform buffer patterns for per-frame/per-object data.
### 4.2 Backend Scope
- **WebGL2 path**
- Acts as compatibility baseline.
- Uses GLSL ES shaders and explicit state batching.
- **WebGPU path**
- Uses WGSL shaders, pipeline objects, bind groups, and explicit buffer lifetimes.
- Initially targets desktop-class browsers where WebGPU is available.

### 4.3 Performance Baseline
- Frustum culling + coarse occlusion strategy.
- Minimize WebGL state changes.
- Batch UI quads and decals.
### 4.3 Feature Rollout Order
Implement both backends in lockstep by feature tier:
1. Clear + camera + static geometry
2. Texture/material system
3. HUD and sprites
4. Particles/decals
5. Post-processing

If a feature ships in WebGPU first, maintain a temporary WebGL2 parity issue until closed.

### 4.4 Shader and Asset Pipeline
- Author shaders with shared conventions and split outputs (GLSL + WGSL).
- Add shader validation in CI for both targets.
- Keep material definition format renderer-neutral and compile to backend-specific descriptors.

### 4.5 Runtime Selection
- Detect support at startup:
- Prefer **WebGPU** when available and stable.
- Auto-fallback to **WebGL2** otherwise.
- Add settings toggle for manual backend override and bug triage.

### 4.6 Performance Baseline
- Shared CPU-side culling and visibility logic.
- Backend-specific GPU optimizations:
- WebGL2: reduce state changes, batch draw calls.
- WebGPU: persist pipelines/bind groups and use ring-buffered dynamic uniforms.

## 5) Security Model
- Validate all gameplay messages server-side.
Expand Down Expand Up @@ -142,3 +165,122 @@ Reuse existing WebSocket channel for WebRTC signaling:
- Perfect visual parity with native renderer on day one.
- Browser P2P authoritative gameplay (server remains authoritative).

## 9) Recommended Repository Layout

Use a monorepo so gameplay protocol types, tooling, and CI are shared.

```
AC/
├─ source/ # existing native engine/server code
├─ docs/
│ └─ web_port_plan.md
├─ web/
│ ├─ apps/
│ │ ├─ client/ # browser game shell (TS host + dual renderer)
│ │ │ ├─ public/
│ │ │ ├─ src/
│ │ │ │ ├─ app/
│ │ │ │ ├─ net/
│ │ │ │ ├─ voice/
│ │ │ │ ├─ input/
│ │ │ │ ├─ telemetry/
│ │ │ │ └─ renderer/
│ │ │ │ ├─ core/ # shared render graph/material interfaces
│ │ │ │ ├─ webgl2/ # WebGL2 backend + GLSL shader paths
│ │ │ │ └─ webgpu/ # WebGPU backend + WGSL shader paths
│ │ │ └─ index.html
│ │ ├─ gateway/ # optional WS<->native bridge during transition
│ │ ├─ signaling/ # WebRTC signaling/session service
│ │ └─ matchmaker/ # lobby + region allocation + server list
│ ├─ packages/
│ │ ├─ protocol/ # packet schema, serializers, versioning
│ │ ├─ shared-config/ # lint/tsconfig/eslint/prettier presets
│ │ ├─ ui/ # reusable HUD/menu web components
│ │ └─ observability/ # metrics/logging SDK wrappers
│ ├─ wasm/
│ │ ├─ CMakeLists.txt
│ │ ├─ src/ # C/C++ bridge code exposed to JS
│ │ └─ build/ # emscripten outputs (.wasm/.js)
│ ├─ tools/
│ │ ├─ asset-pipeline/ # texture packing, model conversion, map bake
│ │ ├─ protocol-gen/ # codegen for packet structs
│ │ └─ replay-tools/ # deterministic replay validators
│ ├─ tests/
│ │ ├─ e2e/
│ │ ├─ integration/
│ │ └─ load/
│ └─ docker/
│ ├─ local-dev/
│ └─ ci/
├─ pnpm-workspace.yaml
└─ turbo.json
```

## 10) Tooling and Bundler Choices

### 10.1 Package Manager + Monorepo
- **pnpm workspaces** for deterministic installs and disk-efficient linking.
- **Turborepo** for task orchestration (`build`, `test`, `lint`, `typecheck`) and remote/local caching.

### 10.2 Browser Client Build
- **Vite** for fast local dev server and production bundles.
- **TypeScript** in strict mode.
- **esbuild** through Vite for fast transforms.
- Keep wasm artifacts as explicit assets loaded by URL (avoid opaque inlining initially).
- Maintain backend entrypoints for `webgl2` and `webgpu`, with runtime capability switching.

### 10.3 WASM Build Pipeline
- **Emscripten + CMake** for C/C++ -> wasm output.
- Export a minimal stable C ABI for JS interop.
- Generate source maps in dev builds for mixed JS/WASM debugging.

### 10.4 Graphics Tooling (Dual Backend)
- **WGSL tooling**: `@webgpu/types` + shader lint/validation in CI.
- **GLSL tooling**: `glslangValidator` (or equivalent) for syntax checks.
- Optional shader codegen layer if you want shared source-of-truth for GLSL/WGSL later.

### 10.5 Realtime + Backend Services
- **Node.js + Fastify** (or uWebSockets.js if you need very high socket fanout) for:
- websocket session services
- signaling and room control plane
- matchmaker APIs
- **Redis** for ephemeral state (presence, room membership, short-lived coordination).

### 10.6 Voice Infrastructure
- Start with a managed/known SFU stack to reduce solo ops burden:
- **LiveKit** (self-hosted or cloud) or **mediasoup** if you want custom control.
- Keep voice authorization coupled to game session JWTs.

### 10.7 Serialization + Validation
- **FlatBuffers** or **Protobuf** for packet schema evolution.
- **zod** (TS side) for config/admin payload validation.
- Protocol package owns schema versioning and compatibility tests.

### 10.8 Quality and CI
- **Vitest** for unit tests (client/packages).
- **Playwright** for browser E2E.
- **k6** (or Artillery) for websocket/session load tests.
- **GitHub Actions** for CI, with matrix jobs:
- wasm build
- web lint/typecheck/tests
- backend service tests

### 10.9 Observability
- **OpenTelemetry** traces/metrics in backend services.
- **Prometheus + Grafana** dashboards for RTT, jitter, reconnect rates, room health.
- **Sentry** for frontend/runtime error tracking.

## 11) Baseline Dev Commands (Suggested)

From repo root after introducing web workspace:

- `pnpm install`
- `pnpm turbo run dev --filter=@ac/client`
- `pnpm turbo run build`
- `pnpm turbo run test`
- `pnpm turbo run lint`

WASM target example:

- `cmake -S web/wasm -B web/wasm/build -DCMAKE_TOOLCHAIN_FILE=$EMSDK/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake`
- `cmake --build web/wasm/build -j`