diff --git a/docs/web_port_plan.md b/docs/web_port_plan.md index 5ae3b4c0b..482ab5cd3 100644 --- a/docs/web_port_plan.md +++ b/docs/web_port_plan.md @@ -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 @@ -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 @@ -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. @@ -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`