# zardoy/minecraft-web-client architecture

> Architecture diagram of the GitHub repository zardoy/minecraft-web-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zardoy/minecraft-web-client
- Repository: https://github.com/zardoy/minecraft-web-client

## Overview

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: [`src/appViewer.ts`](https://github.com/zardoy/minecraft-web-client/blob/next/src/appViewer.ts) (App core), [`src/mineflayer/mc-protocol.ts`](https://github.com/zardoy/minecraft-web-client/blob/next/src/mineflayer/mc-protocol.ts) (Mineflayer bridge), [`renderer/viewer/three/worldrendererThree.ts`](https://github.com/zardoy/minecraft-web-client/blob/next/renderer/viewer/three/worldrendererThree.ts) (Renderer core), [`scripts/build.js`](https://github.com/zardoy/minecraft-web-client/blob/next/scripts/build.js) (Build scripts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["Browser app"]
  node_node_index["App boot<br/>bootstrap<br/>[index.ts]"]
  node_node_app["App core<br/>coordination<br/>[appViewer.ts]"]
  node_node_connect["Connect flow<br/>session<br/>[connect.ts]"]
  node_node_ui["React UI<br/>interface<br/>[reactUi.tsx]"]
  node_node_controls["Input system<br/>[controls.ts]"]
  node_node_world["World & saves<br/>storage<br/>[loadSave.ts]"]
  node_node_protocol["Mineflayer bridge<br/>protocol<br/>[mc-protocol.ts]"]
end

subgraph group_group_renderer["Renderer package"]
  node_node_renderer_entry["Renderer core<br/>rendering"]
  node_node_mesher["Meshing pipeline<br/>geometry<br/>[mesher.ts]"]
  node_node_three["Three.js scene<br/>presentation<br/>[entities.ts]"]
  node_node_playground["Renderer playground<br/>debug scenes<br/>[playground.ts]"]
end

subgraph group_group_runtime["Runtime services"]
  node_node_localserver[("Local server<br/>embedded-server")]
  node_node_resources["Resources<br/>content pipeline"]
  node_node_replay["Packet replay<br/>recording<br/>[replayPackets.ts]"]
end

subgraph group_group_tooling["Tooling"]
  node_node_build["Build scripts<br/>generation<br/>[build.js]"]
  node_node_serverjs["Server entry<br/>deployment<br/>[server.js]"]
  node_node_cypress["E2E tests<br/>testing<br/>[smoke.spec.ts]"]
end

node_node_index -->|"boots"| node_node_app
node_node_app -->|"renders"| node_node_ui
node_node_ui -->|"reads input"| node_node_controls
node_node_app -->|"opens sessions"| node_node_connect
node_node_connect -->|"uses"| node_node_protocol
node_node_protocol -->|"bridges to"| node_node_localserver
node_node_app -->|"loads worlds"| node_node_world
node_node_world -->|"consumes"| node_node_resources
node_node_protocol -->|"records/plays"| node_node_replay
node_node_app -->|"drives view"| node_node_renderer_entry
node_node_renderer_entry -->|"builds geometry"| node_node_mesher
node_node_renderer_entry -->|"draws scene"| node_node_three
node_node_playground -->|"tests meshes"| node_node_mesher
node_node_playground -->|"tests scene"| node_node_three
node_node_build -->|"builds worker"| node_node_mesher
node_node_build -->|"generates data"| node_node_resources
node_node_build -->|"generates types"| node_node_protocol
node_node_serverjs -->|"serves"| node_node_connect
node_node_cypress -->|"verifies"| node_node_app
node_node_cypress -->|"checks render"| node_node_renderer_entry

click node_node_index "https://github.com/zardoy/minecraft-web-client/blob/next/src/index.ts"
click node_node_app "https://github.com/zardoy/minecraft-web-client/blob/next/src/appViewer.ts"
click node_node_connect "https://github.com/zardoy/minecraft-web-client/blob/next/src/connect.ts"
click node_node_ui "https://github.com/zardoy/minecraft-web-client/blob/next/src/reactUi.tsx"
click node_node_controls "https://github.com/zardoy/minecraft-web-client/blob/next/src/controls.ts"
click node_node_world "https://github.com/zardoy/minecraft-web-client/blob/next/src/loadSave.ts"
click node_node_protocol "https://github.com/zardoy/minecraft-web-client/blob/next/src/mineflayer/mc-protocol.ts"
click node_node_localserver "https://github.com/zardoy/minecraft-web-client/blob/next/src/createLocalServer.ts"
click node_node_resources "https://github.com/zardoy/minecraft-web-client/blob/next/src/resourcesManager.ts"
click node_node_replay "https://github.com/zardoy/minecraft-web-client/blob/next/src/packetsReplay/replayPackets.ts"
click node_node_renderer_entry "https://github.com/zardoy/minecraft-web-client/blob/next/renderer/viewer/three/worldrendererThree.ts"
click node_node_mesher "https://github.com/zardoy/minecraft-web-client/blob/next/renderer/viewer/lib/mesher/mesher.ts"
click node_node_three "https://github.com/zardoy/minecraft-web-client/blob/next/renderer/viewer/three/entities.ts"
click node_node_playground "https://github.com/zardoy/minecraft-web-client/blob/next/renderer/playground/playground.ts"
click node_node_build "https://github.com/zardoy/minecraft-web-client/blob/next/scripts/build.js"
click node_node_serverjs "https://github.com/zardoy/minecraft-web-client/blob/next/server.js"
click node_node_cypress "https://github.com/zardoy/minecraft-web-client/blob/next/cypress/e2e/smoke.spec.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_index,node_node_app,node_node_connect,node_node_ui,node_node_controls,node_node_world,node_node_protocol toneBlue
class node_node_renderer_entry,node_node_mesher,node_node_three,node_node_playground toneAmber
class node_node_localserver,node_node_resources,node_node_replay toneMint
class node_node_build,node_node_serverjs,node_node_cypress toneRose
```

## Components

### Browser app

Main TypeScript application running in the browser.

- [App boot](https://github.com/zardoy/minecraft-web-client/blob/next/src/index.ts): bootstrap · Browser entrypoint and top-level startup orchestration. · `src/index.ts`
- [App core](https://github.com/zardoy/minecraft-web-client/blob/next/src/appViewer.ts): coordination · App-wide lifecycle, routing, status, and boot state. · `src/appViewer.ts`
- [Connect flow](https://github.com/zardoy/minecraft-web-client/blob/next/src/connect.ts): session · Server connection, session setup, and transport selection. · `src/connect.ts`
- [React UI](https://github.com/zardoy/minecraft-web-client/blob/next/src/reactUi.tsx): interface · Menus, HUD, overlays, settings, and in-game screens. · `src/reactUi.tsx`
- [Input system](https://github.com/zardoy/minecraft-web-client/blob/next/src/controls.ts): input · Keyboard, mouse, touch, gamepad, and camera control handling. · `src/controls.ts`
- [World & saves](https://github.com/zardoy/minecraft-web-client/blob/next/src/loadSave.ts): storage · World loading, save/export, local files, and resource pack handling. · `src/loadSave.ts`
- [Mineflayer bridge](https://github.com/zardoy/minecraft-web-client/blob/next/src/mineflayer/mc-protocol.ts): protocol · Mineflayer integration, protocol patches, and browser websocket transport. · `src/mineflayer/mc-protocol.ts`

### Renderer package

Dedicated rendering and meshing subsystem.

- [Renderer core](https://github.com/zardoy/minecraft-web-client/blob/next/renderer/viewer/three/worldrendererThree.ts): rendering · Renderer package entry and world rendering coordination. · `renderer/viewer/three/worldrendererThree.ts`
- [Meshing pipeline](https://github.com/zardoy/minecraft-web-client/blob/next/renderer/viewer/lib/mesher/mesher.ts): geometry · Chunk meshing, geometry generation, and worker-friendly world buffers. · `renderer/viewer/lib/mesher/mesher.ts`
- [Three.js scene](https://github.com/zardoy/minecraft-web-client/blob/next/renderer/viewer/three/entities.ts): presentation · Three.js block, entity, item, sky, hand, and effects rendering. · `renderer/viewer/three/entities.ts`
- [Renderer playground](https://github.com/zardoy/minecraft-web-client/blob/next/renderer/playground/playground.ts): debug scenes · Isolated scenes for renderer debugging and experimentation. · `renderer/playground/playground.ts`

### Runtime services

Transport, local server, resource loading, and replay flows.

- [Local server](https://github.com/zardoy/minecraft-web-client/blob/next/src/createLocalServer.ts): embedded-server · Singleplayer/offline server path and local multiplayer support. · `src/createLocalServer.ts`
- [Resources](https://github.com/zardoy/minecraft-web-client/blob/next/src/resourcesManager.ts): content pipeline · Resource packs, metadata, and sound/item content management. · `src/resourcesManager.ts`
- [Packet replay](https://github.com/zardoy/minecraft-web-client/blob/next/src/packetsReplay/replayPackets.ts): recording · Recorded packet playback and replay-state integration. · `src/packetsReplay/replayPackets.ts`

### Tooling

Build, deployment, and test entrypoints.

- [Build scripts](https://github.com/zardoy/minecraft-web-client/blob/next/scripts/build.js): generation · Type generation, asset preparation, worker build, and optimization scripts. · `scripts/build.js`
- [Server entry](https://github.com/zardoy/minecraft-web-client/blob/next/server.js): deployment · Node entrypoint for self-hosting and proxy-style serving. · `server.js`
- [E2E tests](https://github.com/zardoy/minecraft-web-client/blob/next/cypress/e2e/smoke.spec.ts): testing · Browser smoke tests and rendering performance checks. · `cypress/e2e/smoke.spec.ts`

## Connections

- 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.
