How zardoy/minecraft-web-client works
1. Overall shape
- This repo is a single TypeScript monorepo for a Minecraft web client, but it is not “just a frontend.” It bundles a browser app, a 3D renderer, protocol/client logic, an integrated offline server, and a proxy/server entrypoint for self-hosting.
- The architecture is split between browser runtime code in src/, rendering-heavy code in renderer/, and Node-based build/proxy/server utilities in scripts/, server.js, and Docker files.
2. Primary application orchestration
- src/ is the main application layer: startup, configuration, state, game lifecycle, connectivity, world loading, and app-wide coordination.
- Files like src/index.ts, src/appViewer.ts, src/connect.ts, src/loadSave.ts, src/globalState.ts, and src/app/* indicate this layer owns bootstrapping, session management, and routing the user into multiplayer, singleplayer, replay, or editor-like flows.
3. Network and protocol boundary
- The client does not talk to Minecraft servers directly over TCP in the browser. Instead, src/mineflayer/* wraps Mineflayer and related protocol utilities, while proxy support bridges browser WebSockets to TCP Minecraft servers.
- This creates a clear boundary: browser-side code handles protocol semantics, player state, and gameplay logic; the separate proxy process handles the transport bridge to real servers.
4. Singleplayer / embedded server subsystem
- The repo includes a built-in offline server path for singleplayer and local worlds, backed by src/createLocalServer.ts, src/localServerMultiplayer.ts, and the src/mineflayer/java-tester / src/customServer.ts ecosystem.
- World loading is a major subsystem: zip files, folders, and streamed maps are supported, with storage and save/export flow going through src/loadSave.ts, src/resourcePack.ts, src/resourcesManager.ts, and server-side world options.
- This means the app supports both “connect to external server” and “host a local playable world” modes using the same client surface.
5. Rendering architecture
- Rendering is split into a dedicated renderer/ package, which is itself structured into a world renderer, Three.js-specific scene/render helpers, a meshing pipeline, and playground/demo scenes.
- renderer/viewer/lib/mesher/* handles chunk meshing and geometry generation, while renderer/viewer/three/* contains the Three.js presentation layer for blocks, entities, items, sky, panorama, fire, hand, and world rendering.
- The README notes chunk rendering uses geometry buffers prepared by multiple mesher workers, so the renderer is explicitly workerized for performance.
6. UI and HUD layer
- Most player-facing UI is in src/react/, built as a large React component library rather than a single monolithic app shell.
- This layer includes menus, overlays, HUD bars, chat, inventory-like screens, settings, touch controls, replay panels, modal flows, and status widgets. Many components have Storybook stories, indicating the UI is designed as reusable, isolated primitives.
- Providers such as *Provider.tsx files suggest state is distributed through React context boundaries rather than centralized in the renderer.
7. Input, controls, and interaction
- Input is its own subsystem: keyboard/mouse/gamepad/touch/VR-related control paths are handled by files such as src/controls.ts, src/cameraRotationControls.ts, src/gamepadCursor.ts, src/mobileShim.ts, and the touch-control React components.
- The app also exposes gameplay commands, drag-and-drop world loading, fullscreen handling, and debug keybindings, so interaction is mediated both through DOM/UI and through in-game control state.
8. Resource and content pipelines
- Resource packs, textures, sound maps, and item/block metadata are first-class inputs to the client. Relevant code lives in src/resourcePack.ts, src/resourcesManager.ts, src/resourcesSource.ts, src/sounds/*, and src/itemsDescriptions.ts.
- The repo contains a lot of generated/static game data, such as src/generatedClientPackets.ts, src/generatedServerPackets.ts, src/mcDataTypes.ts, and renderer-side entity/model JSON and OBJ assets. This indicates a build-time data generation pipeline is central to correctness and compatibility.
9. Worker, build, and generated-artifact boundary
- Build scripts under scripts/ generate types, optimize block data, patch assets, prepare sounds, and build workers/mesher bundles. That implies a strong separation between source code and generated runtime data.
- The presence of buildMesherWorker.mjs, genMcDataTypes.ts, optimizeBlockCollisions.ts, and similar scripts shows the repo depends on preprocessing to keep runtime performance acceptable in the browser.
10. Tooling and auxiliary runtimes
- The project is heavily tested and benchmarked using Vitest and Cypress, with browser-based smoke tests and rendering performance tests. Storybook is used for visual development of UI components.
- There are also experiment sandboxes under experiments/ and renderer playgrounds under renderer/playground/, which act as isolated execution environments for debugging rendering, state, and interaction behavior.
11. Deployment and self-hosting
- Deployment is supported through GitHub Actions, Vercel, Docker, and a dedicated proxy mode. Dockerfile, Dockerfile.proxy, server.js, and scripts/wsServer.ts indicate the repo can be run as a full self-hosted stack.
- The README makes a clear deployment distinction: full app + proxy, or proxy-only via a separate service. That is an important architectural boundary because the browser client itself is not the transport bridge.
12. What to draw in an architecture diagram
- The most important nodes are: browser app shell, React UI layer, Mineflayer/protocol layer, renderer/Three.js layer, meshing workers, local server/world storage, and external Minecraft servers reached through a proxy.
- The main data flows are: user input → app/UI state → protocol/client logic → server or local server; and world/protocol updates → renderer meshing → Three.js scene → browser display.
- Secondary flows include world/resource loading from zip/folder/URL, replay packet ingestion, and build-time generation of assets/types that feed both the client and renderer.
Main entry points: appViewer.ts App core · mc-protocol.ts Mineflayer bridge · worldrendererThree.ts Renderer core · build.js Build scripts
Components 17
Browser app
Main TypeScript application running in the browser.
- App boot · Browser entrypoint and top-level startup orchestration.
src/index.ts - App core · App-wide lifecycle, routing, status, and boot state.
src/appViewer.ts - Connect flow · Server connection, session setup, and transport selection.
src/connect.ts - React UI · Menus, HUD, overlays, settings, and in-game screens.
src/reactUi.tsx - Input system · Keyboard, mouse, touch, gamepad, and camera control handling.
src/controls.ts - World & saves · World loading, save/export, local files, and resource pack handling.
src/loadSave.ts - Mineflayer bridge · Mineflayer integration, protocol patches, and browser websocket transport.
src/mineflayer/mc-protocol.ts
Renderer package
Dedicated rendering and meshing subsystem.
- Renderer core · Renderer package entry and world rendering coordination.
renderer/viewer/three/worldrendererThree.ts - Meshing pipeline · Chunk meshing, geometry generation, and worker-friendly world buffers.
renderer/viewer/lib/mesher/mesher.ts - Three.js scene · Three.js block, entity, item, sky, hand, and effects rendering.
renderer/viewer/three/entities.ts - Renderer playground · Isolated scenes for renderer debugging and experimentation.
renderer/playground/playground.ts
Runtime services
Transport, local server, resource loading, and replay flows.
- Local server · Singleplayer/offline server path and local multiplayer support.
src/createLocalServer.ts - Resources · Resource packs, metadata, and sound/item content management.
src/resourcesManager.ts - Packet replay · Recorded packet playback and replay-state integration.
src/packetsReplay/replayPackets.ts
Tooling
Build, deployment, and test entrypoints.
- Build scripts · Type generation, asset preparation, worker build, and optimization scripts.
scripts/build.js - Server entry · Node entrypoint for self-hosting and proxy-style serving.
server.js - E2E tests · Browser smoke tests and rendering performance checks.
cypress/e2e/smoke.spec.ts
Connections 20
- App boot → App core: boots · Startup enters the app coordination layer.
- App core → React UI: renders · App state is exposed through React UI surfaces.
- React UI → Input system: reads input · UI and gameplay screens depend on shared input state.
- App core → Connect flow: opens sessions · App routes the user into multiplayer or local sessions.
- Connect flow → Mineflayer bridge: uses · Connection flows are mediated by Mineflayer/protocol logic.
- Mineflayer bridge → Local server: bridges to · Singleplayer and local multiplayer use an embedded server path.
- App core → World & saves: loads worlds · World selection, save management, and resource loading live here.
- World & saves → Resources: consumes · Worlds depend on packs, metadata, textures, and sounds.
- Mineflayer bridge → Packet replay: records/plays · Packet capture and replay sit on the protocol boundary.
- App core → Renderer core: drives view · Gameplay state is projected into the renderer.
- Renderer core → Meshing pipeline: builds geometry · World rendering depends on chunk meshing and geometry prep.
- Renderer core → Three.js scene: draws scene · Three.js presentation layer renders blocks, entities, and effects.
- Renderer playground → Meshing pipeline: tests meshes · Playground scenes exercise meshing and rendering behaviors.
- Renderer playground → Three.js scene: tests scene · Renderer experiments target Three.js presentation features.
- Build scripts → Meshing pipeline: builds worker · Scripts prepare the mesher worker bundle and related assets.
- Build scripts → Resources: generates data · Scripts produce optimized game data and content artifacts.
- Build scripts → Mineflayer bridge: generates types · Build-time generation feeds protocol and packet typing.
- Server entry → Connect flow: serves · Self-hosting entrypoint supports browser connectivity.
- E2E tests → App core: verifies · End-to-end tests exercise the browser app flows.
- E2E tests → Renderer core: checks render · Performance and smoke tests cover renderer output.