Rewrite Proxima in TypeScript with Babylon.js as a browser-first game

[michidk]

Proposal

Rewrite Proxima in TypeScript with Babylon.js and retire the Unreal Engine implementation once feature parity is reached.

This should be a browser-first game rather than an Unreal game with browser controls attached to it. The main screen, authoritative simulation, and crew stations can all run on the web platform and share one language, one type system, one protocol, and one development pipeline.

Target architecture

Host browser

The player opening a new game becomes the authoritative host:

• Babylon.js renders the third-person pilot view.
• The authoritative simulation runs in TypeScript inside a Web Worker so rendering and UI work cannot stall the simulation loop.
• The host owns mission state, ship systems, physics, combat, AI, persistence, and validation of crew actions.
• Save data can use IndexedDB or OPFS, with explicit export/import for portable saves.

A separate Node or Bun game server is not required for normal play.

Crew browsers

Crew members join through a room link, short code, or QR code. Their browsers connect directly to the host browser through encrypted WebRTC data channels.

• WebRTC carries station commands and authoritative state updates.
• A small signaling/rendezvous service exchanges connection offers and ICE candidates, but does not run the game simulation.
• STUN provides peer discovery; TURN is the relay fallback when direct connectivity fails.
• When a direct path is available, gameplay data flows between the host and crew peers rather than through the application server.

This is a star topology: the host browser remains authoritative and each station connects to it. The browser is genuinely the game server at the application level even though WebRTC uses signaling to establish the connection.

Shared packages

A TypeScript workspace can separate concerns without separating ecosystems:

• packages/sim - deterministic game state, systems, AI, missions, combat, economy
• packages/protocol - runtime-validated messages, snapshots, commands, versions
• packages/renderer - Babylon.js scene, camera, materials, particles, audio, FX
• packages/ui - shared HUD and station components
• apps/game - host/pilot browser application
• apps/station - crew station application
• apps/signaling - room codes and WebRTC signaling

The simulation package should not depend on Babylon or the DOM. That keeps it headless, testable, replayable, and reusable by the host worker.

WebRTC versus WebSockets

Both technologies are useful, but they solve different parts of this architecture.

Concern	WebRTC data channels	WebSockets
Browser as authoritative host	Supports direct browser-to-browser gameplay connections	A browser can connect to a WebSocket server but cannot itself listen as one, so an external authoritative server would be required
Topology	Peer-to-peer; Proxima can use a host-centered star	Client/server; every client connects to hosted infrastructure
Setup	More complex: signaling, ICE, STUN, and optional TURN	Simpler connection setup and operational model
Delivery modes	Supports reliable ordered data and configurable unordered or limited-retransmission channels	Reliable, ordered byte/message stream over TCP
Latency behavior	Can avoid head-of-line blocking for transient state when unordered/unreliable channels are used deliberately	TCP ordering means lost packets can delay later messages
Infrastructure cost	Normal gameplay is direct when possible; TURN relays only when needed	All gameplay traffic and authoritative simulation depend on server infrastructure
Encryption	Mandatory DTLS encryption for data channels	Secure deployments require WSS/TLS
Reconnect and debugging	More connection states and ICE behavior to handle	Mature and comparatively straightforward
Backpressure	Exposes bufferedAmount and low-threshold events; message sizing and pacing still need design	Stable WebSocket has no receive backpressure; send queues must be monitored. WebSocketStream adds streams but remains non-standard and has limited support
Offline/shared-LAN story	Direct peer paths are possible, but initial negotiation still needs signaling or an explicit out-of-band exchange	Requires a reachable WebSocket server on the LAN or internet

Recommendation

Use a hybrid:

• WebSockets between each browser and the signaling service for room creation, join codes, offers, answers, ICE candidates, and presence.
• WebRTC data channels between the authoritative host browser and crew browsers for gameplay commands, snapshots, events, and connection statistics.

This preserves the desired browser-hosted architecture. Replacing WebRTC gameplay with WebSockets would move the authoritative runtime back into hosted infrastructure or require a separately installed local server, undermining a central reason for the rewrite.

WebRTC should use separate logical channels where useful:

• reliable/ordered for purchases, mission choices, docking, inventory, and other durable commands;
• unordered or limited-retransmission for frequent transient snapshots where a newer update supersedes an old one;
• explicit sequence numbers, acknowledgements where needed, rate limits, state resynchronization, and host-authoritative validation above the transport.

References:

• Using WebRTC data channels
• WebRTC signaling and ICE
• W3C WebRTC specification
• MDN WebSocket API

Why replace Unreal?

Proxima is already partly a web application:

• the crew uses mobile-first web consoles over LAN;
• the game embeds an HTTP server and translates game state into station endpoints through StationServerSubsystem.cpp, currently about 90 KB of C++;
• the architecture already separates authoritative simulation from presentation (DECISIONS.md).

The current Unreal workflow imposes costs disproportionate to this use case:

• UE 5.7, Linux/Vulkan, a discrete GPU, and roughly 150 GB of disk are required for development (README);
• the verified Linux release pipeline takes roughly 30 minutes and requires Epic/GitHub linking, EULA acceptance, private container access, and repository credentials;
• Windows requires a self-hosted machine with Unreal installed;
• macOS packaging is not implemented and requires Apple hardware (CI documentation);
• packaging is already identified as the highest release risk (RELEASE_PLAN.md);
• agent-assisted development depends on UnrealClaude, VibeUE, editor state, MCP/Python automation, and viewport-driven workflows.

Removing Unreal removes this engine-specific development, automation, build, packaging, and distribution layer.

Graphics are viable on the modern web

This rewrite does not require reproducing every Unreal feature. It needs to reproduce the features Proxima actually uses:

• ships, planets, stations, and sector environments;
• emissive and physically based materials;
• a nebula and starfield;
• third-person cameras;
• beams, explosions, debris, and projectiles;
• tactical overlays and station interfaces;
• spatial audio and UI feedback.

Babylon.js provides TypeScript/npm modules, WebGPU with continued WebGL support, PBR and custom materials, glTF loading, particles, post-processing, audio, GUI, physics integrations, an inspector, and browser/mobile support. See the Babylon.js documentation and WebGPU support notes.

A standard glTF-centered asset pipeline makes assets easier to inspect, optimize, convert, automate, and reuse outside a proprietary editor workflow.

WebGPU improves the available rendering ceiling on supported browsers while WebGL remains the compatibility path. The renderer can select the best available backend instead of making WebGPU an absolute requirement.

Babylon.js versus alternatives

The renderer should be selected for the needs of a complete browser game, not only for drawing a scene.

Option	Strengths	Tradeoffs for Proxima
Babylon.js	Full code-first engine; strong TypeScript/npm support; WebGL and WebGPU; PBR, glTF, particles, post-processing, audio, physics integrations, GUI, inspector, serializers, and performance tooling in one ecosystem	Larger and more opinionated than a rendering-only library; engine abstractions must be kept out of the authoritative simulation package
Three.js	Widely used, flexible, lightweight general-purpose 3D library; WebGL and WebGPU renderers; strong glTF/PBR support; TSL provides composable shaders across backends; very large ecosystem	It is primarily a rendering library. Physics, game architecture, UI, asset lifecycle, audio strategy, debugging conventions, and many engine services must be selected and integrated separately
PlayCanvas Engine	Full browser game engine with an entity/component model, WebGL2 and WebGPU, rendering, animation, physics, audio, input, and an established visual editor; engine is open source and installable from npm	Core engine source is JavaScript with generated TypeScript definitions rather than TypeScript-first implementation. The visual-editor workflow can reintroduce editor state and automation concerns that this rewrite is intended to remove, although the engine can be used code-first
React Three Fiber	Declarative React renderer for Three.js; excellent integration with web UI and a large component ecosystem; useful for UI-heavy 3D applications	Not a standalone engine. It inherits the Three.js integration decisions, adds React reconciliation to the render architecture, and is not an obvious fit for a high-frequency authoritative game loop. It could still be useful around tools or selected UI surfaces
Godot web export or another native-to-Wasm engine	Mature game-editor features and a conventional scene workflow	Does not meet the main goal of one TypeScript/web codebase and retains a separate engine/editor/export pipeline, so it solves fewer of the current development and agent-workflow problems

Why Babylon.js is the recommended choice

Babylon.js offers the best balance for this rewrite:

1. More complete than Three.js. Proxima needs a game renderer, asset loading, materials, particles, audio, physics integration, inspection, profiling, and browser compatibility. Babylon supplies these as a coherent engine instead of requiring the project to assemble and maintain a custom engine stack.
2. More code-first than a PlayCanvas-editor workflow. The whole architecture can remain in versioned TypeScript modules and standard build/test commands.
3. Less framework coupling than React Three Fiber. React can still power menus and station interfaces without controlling the core render loop.
4. Designed for both WebGL and WebGPU. The project can use WebGPU where available without abandoning a broad compatibility path.
5. Good separation boundary. Babylon can remain confined to packages/renderer, while packages/sim stays portable, deterministic, and headless.

Three.js is the strongest alternative if the project values maximum rendering flexibility and accepts owning more engine architecture. PlayCanvas is the strongest alternative if a collaborative visual editor is considered more valuable than a purely code-first workflow.

References:

• Babylon.js
• Three.js repository and scope
• Three.js WebGPU documentation
• PlayCanvas Engine
• React Three Fiber

Benefits

One language and one model

The simulation, network protocol, pilot HUD, renderer integration, and crew stations can share TypeScript types and runtime schemas. This eliminates much of the current C++ to JSON to embedded web UI translation layer and prevents protocol drift.

Simpler development

The workflow becomes standard web tooling:

• clone the repository;
• install dependencies;
• start the development server;
• receive fast hot reload for UI and rendering work;
• run simulation and protocol tests without opening a game editor;
• inspect network messages, rendering, memory, and performance with browser tooling.

Contributors working on gameplay logic, UI, tests, missions, documentation examples, or tooling no longer need a 150 GB engine installation.

Better development with coding agents

The advantage is not that agents are inherently better at TypeScript. The advantage is that the complete project becomes accessible through text files and standard commands.

Agents can:

• run the simulation headlessly;
• write and execute unit, integration, and browser tests;
• use Playwright for complete multiplayer flows;
• capture deterministic screenshots and visual regressions;
• inspect schemas and types without driving Unreal reflection or Blueprint graphs;
• build and preview changes in isolated environments;
• reproduce CI locally with the same commands.

This removes dependence on stateful editor sessions and specialized Unreal MCP plugins.

Easier distribution

The browser build can be deployed as static assets to a CDN and opened through a URL. Players do not need platform-specific game packages for the main client.

This enables instant public demos, immediate updates, cross-platform access from one build, PWA installation and offline caching, optional Electron/Tauri packaging, easier itch.io distribution, and shareable test builds for every pull request.

Only the lightweight signaling service needs conventional hosting for room discovery. It is not the authoritative game runtime.

More contributors

TypeScript, HTML, CSS, WebRTC, and Babylon.js provide a broader contribution surface than an Unreal C++ project tied to a specific editor version and host setup.

Contributors can work independently on station interfaces, pilot HUD and accessibility, rendering and effects, missions and balance data, networking, tests and replay tooling, localization, scenario editors, mod support, documentation, and embedded examples.

Better testing and reliability

A renderer-independent simulation can support fixed-step deterministic tests, recorded command streams, campaign simulations in CI, protocol compatibility tests, reconnect and packet-loss tests, browser matrix testing, visual regression, and performance budgets.

One UI platform

The current project maintains Unreal/UMG widgets in C++ alongside browser station interfaces. A web rewrite allows the pilot HUD, menus, settings, and crew stations to share components, styling, input behavior, accessibility semantics, and localization.

Easier content and modding

Ships, upgrades, missions, contracts, enemy archetypes, and balance values can move to runtime-validated portable formats. This makes content easier to review, test, generate, and edit through browser-based tools.

Better observability and security boundaries

The rewrite can define a versioned command protocol rather than accumulating handwritten endpoints. Commands can be validated at runtime and checked against authoritative simulation state. WebRTC data channels are encrypted, and the signaling service only needs short-lived room metadata.

Structured event logs, traces, replay files, connection statistics, and browser performance profiles become straightforward to capture.

Rewrite scope

The rewrite should replace the Unreal implementation rather than permanently maintaining two engines.

It includes:

• ship movement, gravity, collision, docking, and warp;
• power, health, shields, subsystem damage, repair, science, weapons, and torpedoes;
• enemy AI and archetypes;
• campaign missions, travel events, contracts, progression, saves, and skirmish mode;
• Babylon.js rendering, assets, materials, audio, particles, and post-processing;
• pilot controls, HUD, menus, settings, and outcome screens;
• all crew stations;
• browser-hosted authoritative multiplayer through WebRTC;
• signaling, room codes, reconnect handling, and connection diagnostics;
• browser-first distribution and optional installable packaging.

Suggested migration order

1. Establish the TypeScript workspace, shared schemas, fixed-step simulation loop, and host Web Worker.
2. Port core ship systems and verify them with headless tests.
3. Build the Babylon.js sector, ships, camera, HUD, and core effects.
4. Implement browser-hosted rooms with WebRTC data channels and the signaling service.
5. Port Helm, Weapons, Engineering, and Science against the shared protocol.
6. Port enemies, campaign progression, economy, saves, events, contracts, and skirmish.
7. Convert and optimize art/audio assets through a documented glTF-centered pipeline.
8. Add replay tests, multiplayer browser tests, visual regression, and performance coverage.
9. Ship the browser/PWA release, optionally add a desktop wrapper, and archive the Unreal implementation after parity.

Important engineering constraints

A full browser rewrite should deliberately address:

• fixed simulation timestep independent of render frame rate;
• host migration or a clear outcome when the host tab closes;
• reconnect and state resynchronization;
• tab suspension and background throttling;
• versioned protocol and save migrations;
• WebRTC signaling plus TURN fallback where direct connectivity fails;
• explicit browser/GPU support policy;
• WebGL fallback where practical;
• asset compression, lazy loading, and caching;
• garbage collection and allocation discipline in hot paths;
• host-authoritative command validation;
• offline/PWA behavior when signaling is unavailable;
• accessibility for station UIs and menus.

Expected result

Proxima becomes a browser-native cooperative bridge simulator:

• one player opens the game and hosts the authoritative simulation in a browser;
• crew joins from phones, tablets, or laptops with a link, code, or QR scan;
• Babylon.js renders the main view at the desired visual quality;
• the complete project builds, tests, previews, and deploys through a standard TypeScript/web pipeline;
• Unreal Engine and its build, packaging, plugin, and editor automation requirements are removed.

[invertium]

Opened #18 as an attempt at this — with one deliberate departure: Three.js rather than Babylon.js.

The engine-completeness argument here for Babylon is fair, and I've recorded in the PR (and the README) where Babylon would genuinely have won: the Node Material Editor, exotic glTF extension fidelity, and not having to hand-assemble physics/audio/GUI. That last is a real cost the branch hasn't paid yet.

What tipped it was the two axes that matter most for how this project is actually developed:

1. Most of a bridge sim's visual surface is procedural code, not sculpted assets — starfield, planets, beams, blasts, radar overlays. The tooling for generating Three.js code (img2threejs and its class) has no Babylon equivalent and doesn't port: different geometry constructors, different material system, different handedness.
2. ~3.5M vs ~400K weekly downloads — roughly 9:1 of training-data representation, which shows up directly in how much lookup an agent needs per change.

Worth flagging honestly: the renderer boundary the issue proposes (packages/renderer) protects the simulation, but codegen output lands inside that boundary. Picking Three.js is not a cost-free decision to revisit later.

The PR is a feature-complete port of the 12.5k-line C++ game — sim, renderer, four crew consoles over a LAN relay — with 198 unit tests, a headless full-campaign replay, 12 browser E2E journeys, and a tunable-drift test against the C++ values. The Unreal implementation is untouched; nothing is archived.

Everything in the issue's "Important engineering constraints" list that remains outstanding is enumerated under §Not done: no WebRTC (LAN only), no host migration, no reconnect resync, no accessibility pass.