Prismarine Web Client

1.6.0 verified Sat Apr 25 auth: no javascript

Prismarine Web Client is a browser-based Minecraft client that allows users to connect to and interact with Minecraft servers directly from a web page. It leverages the `mineflayer` library for high-level bot API interactions and `prismarine-viewer` for 3D world rendering within the browser. The current stable version is 1.6.0, with releases appearing somewhat frequently, indicating active development. A key differentiator is its ability to run entirely client-side in a web browser, connecting to standard Minecraft TCP servers via an intermediary WebSocket-to-TCP proxy that is bundled and managed by the CLI tool. This package is primarily distributed as a globally installable command-line tool that serves the client application, rather than a library intended for direct `import` into other JavaScript projects for code-level integration. Developers can interact with the running client's core functionalities, such as the `bot` instance and `viewer` for debugging and custom extensions, through global `window` objects.

Common errors

error ReferenceError: bot is not defined ↓

cause The `bot` object (or `viewer`, `mcData`, etc.) is accessed in the browser console before the client application has fully initialized or before the `window` global has been populated with these objects.

fix

Ensure the web client is fully loaded in your browser and that you are interacting with the correct browser window's developer console. Verify access via window.bot.

error WebSocket connection to 'ws://localhost:XXXX/' failed: WebSocket is closed before the connection is established. ↓

cause The `prismarine-web-client` CLI tool, which acts as both the web server and the WebSocket-to-TCP proxy, is not running, or a network configuration (e.g., firewall) is blocking the connection to `localhost`.

fix

Verify that prismarine-web-client is running in your terminal and listening on the expected port (default 8080). Check for any local firewall rules or network issues preventing connection to localhost.

error Cannot find module 'prismarine-web-client' (e.g., in a Node.js project or another browser bundle) ↓

cause The `prismarine-web-client` npm package is primarily designed as a standalone application that serves a web client. It is not typically intended for programmatic `import` into other Node.js or browser projects in the usual module fashion. Its core functionalities are exposed as globals within its *own* served browser environment.

fix

To run the client, use the global installation and execution commands: npm install -g prismarine-web-client followed by prismarine-web-client. If you intend to use underlying functionalities like the Minecraft client API or 3D viewer programmatically in a separate project, install and import mineflayer or prismarine-viewer directly.

Warnings

gotcha The `prismarine-web-client` requires an intermediary WebSocket proxy (automatically handled by the CLI tool) to translate browser WebSocket connections to standard Minecraft TCP server connections. Direct connection to TCP servers from the browser is not possible due to browser security restrictions. ↓

fix Ensure the `prismarine-web-client` CLI is running correctly, as it provides the necessary proxy and web server for the client.

gotcha Core API objects like `bot`, `viewer`, `mcData`, `worldView`, `Vec3`, and `debugMenu` are exposed as global variables on the `window` object within the served browser application (e.g., `window.bot`) for debugging and direct interaction. Attempting to `import` these directly as modules from the `prismarine-web-client` npm package will not work as expected. ↓

fix Access these objects directly via the `window` global in the browser's developer console or in custom scripts injected into the web page after the client has loaded.

gotcha When developing locally using `npm start`, the Webpack build process will recompile the client application on every file save, which the README notes can take up to 5 seconds per change. This can significantly slow down the development feedback loop. ↓

fix Consider disabling auto-saving features in your Integrated Development Environment (IDE) or exploring Webpack configuration options for more granular control over rebuild triggers to optimize the development experience.

Install

npm install prismarine-web-client

yarn add prismarine-web-client

pnpm add prismarine-web-client

Imports

bot
wrong
```
import { bot } from 'prismarine-web-client'
```
correct
```
window.bot
```
The `bot` instance is exposed globally in the browser environment served by the client, not typically imported as a module from the package itself.
viewer
wrong
```
import { viewer } from 'prismarine-web-client'
```
correct
```
window.viewer
```
The 3D viewer instance is exposed globally in the browser environment for debugging and interaction.
debugMenu
wrong
```
import { debugMenu } from 'prismarine-web-client'
```
correct
```
window.debugMenu
```
The `debugMenu` object is exposed globally for extending and customizing the client's debug capabilities.

Quickstart

Demonstrates how to globally install, run, and then interact with the served Minecraft web client via browser console commands.

npm install -g prismarine-web-client

# Run the client, which starts a web server and proxy
prismarine-web-client

# Open your browser and navigate to the client. Typically:
# http://localhost:8080

// --- Interact with the client in your browser's developer console ---
// Example: Send a chat message
// window.bot.chat('Hello from prismarine-web-client!');

// Example: Make the bot jump
// window.bot.entity.position.y += 5;

// Example: Find a diamond ore block within 256 blocks
// const diamondOrePos = window.bot.findBlock({
//   matching: (block) => block.name === 'diamond_ore',
//   maxDistance: 256
// });
// if (diamondOrePos) {
//   console.log('Diamond ore found at:', diamondOrePos.position);
// } else {
//   console.log('No diamond ore found nearby.');
// }