Contributing Guide

Getting Started

After forking the repository, follow these steps to get the development environment running:

Install Node.js

Ensure you have Node.js installed (tested on v22.x):

node -v

Enable corepack:

corepack enable

If you get Cannot find matching keyid, update corepack:

npm i -g corepack

Install Dependencies

Install all project dependencies:

pnpm i

Start Development

Start the project in development mode:

pnpm start

Or build for production:

pnpm build

Start Contributing

Read the Tasks Categories and Workflow sections below, then start coding!

Project Structure

The project consists of three main parts:

1. Core (`src/`)

The main application source code that integrates all other parts. Technology: Originally Webpack, migrated to Esbuild, now using Rsbuild. Scripts:

# Start development server
pnpm start
pnpm dev-rsbuild  # Without proxy server

# Build for production
pnpm build

Key Directories:

src/ - Main app source code
src/react/ - React components and UI
- Almost all UI components are here
- Each component has a base (reused in app and storybook)
- Providers wrap components and supply context
- Check DeathScreen component as an example

2. Renderer (`renderer/`)

Improved version of prismarine-viewer for rendering the game world. Key Files:

renderer/viewer/lib/worldrenderer.ts - Adds objects to Three.js (sections)
renderer/viewer/lib/models.ts - Prepares rendering data (blocks) in worker
renderer/playground/playground.ts - Playground for testing rendering

Playground Scripts:

# Start playground + mesher + server
pnpm run-playground

# Watch mode
pnpm watch-playground

# Build
pnpm build-playground

Mesher Scripts:

# Watch mesher worker
pnpm watch-mesher

# Build mesher
pnpm build-mesher

3. Storybook (`.storybook/`)

Tool for developing and testing React components in isolation. Location: All stories are in src/react/**/*.stories.tsx Scripts:

# Start Storybook
pnpm storybook

# Build static Storybook
pnpm build-storybook

Development Scripts

Common Commands

# Start main app + playground
pnpm run-all

# Start everything except Storybook and tests
pnpm run-all

# Run linter
pnpm lint

# Fix linting issues
pnpm lint-fix

# Type checking
tsc

Testing

# Unit tests (Vitest)
pnpm test-unit

# E2E tests (Cypress)
pnpm test-mc-server  # Start test server first
pnpm prod-start      # In another terminal
pnpm test:cypress    # Run tests

# Open Cypress UI
pnpm test:cypress:open

# Benchmark tests
pnpm test:benchmark

Production Build

# Build everything
pnpm build

# Start production server
pnpm prod-start

# Or use start-prod after building
pnpm start-prod

Architecture Details

How Modules Work

Mineflayer:

Provides the bot variable
Wrapper for node-minecraft-protocol
Used to connect and interact with Minecraft servers
Not all events are exposed - sometimes need bot._client.on('packet_name', ...)
Supports most mineflayer plugins

Example:

// Standard mineflayer API
bot.on('spawn', () => {
  console.log('Spawned!')
})

// Access underlying client for packets
bot._client.on('entity_metadata', (packet) => {
  console.log('Entity metadata:', packet)
})

Tasks Categories

Contributions are welcome in these areas (ordered by current priority):

1. Client-Side Logic (High Priority)

Everything related to client-side packets and server compatibility. Priority Tasks:

Rewrite or fix physics logic (use Botcraft or Grim as reference)
Implement basic minecart/boat/horse riding
Fix auto-jump module (false triggers, performance)
Investigate connection issues with specific servers
Set up automated testing against anti-cheat plugins

Goals:

Make more servers playable
Fix anti-cheat detection issues

Debugging Tips:

// Enable packet logging
options.debugLogNotFrequentPackets = true

// Or record and replay packets
// Settings → Advanced → Enable Packets Replay

2. Three.js Renderer

Improve and fix rendering issues. Example Tasks:

Improve/fix entity rendering
Update entities on specific packets
Investigate performance issues
Work on playground code

Goals:

Fix entity rendering issues (including position updates)
Implement camera mode switching (first/third person)
Add animated blocks
Add armor rendering

Tip: Learn how to use Three.js helpers and additional cameras (e.g., setScissor)

3. Server-Side Logic

Contribute to Flying Squid fork (space-squid). Example Tasks:

Add missing commands (e.g., /scoreboard)
Basic physics (fall damage, falling blocks)
Entity AI (spawning, attacking)
PvP implementation
Emit packets on specific events
Make adventure maps playable

Long-Term Goals:

Make most adventure maps playable
Enable game completion from scratch (crafting, dimensions, terrain)
Make Bedwars playable

4. Frontend/UI

Create new React components and improve UI (including mobile support). Examples:

New UI screens
Mobile touch controls improvements
Accessibility features
Settings UI enhancements

Development Workflow

Identify the Problem

Test on public server or local setup
Create reproducible environment
Document the issue

Debug and Isolate

Use browser DevTools
Enable packet logging if needed
Use debugger to step through code
Isolate the root cause

Develop and Test

Write fix or feature
Test thoroughly
Add tests if possible (unit or E2E)

Verify Solution

Repeat step 1 to confirm fix
Test edge cases
Ensure no regressions

Making Protocol Changes

When working with Minecraft protocol:

Protocol Documentation

Latest version: wiki.vg/Protocol
Previous versions: wiki.vg/Protocol_version_numbers

Generated Packet Files

src/generatedClientPackets.ts - Server → Client packets
src/generatedServerPackets.ts - Client → Server packets

These are generated from minecraft-data.

Linking Dependencies Locally

To test changes in dependencies like flying-squid:

// package.json
{
  "pnpm": {
    "overrides": {
      "flying-squid": "file:../space-squid"
    }
  }
}

Or use pnpm link:

cd ../space-squid
pnpm link .
cd ../minecraft-web-client
pnpm link flying-squid

Updating Dependencies

Update Git Dependencies

Check and update git-based dependencies:

pnpm update-git-deps

This will:

Show which git dependencies have updates
Ask if you want to update them
Skip dependencies in pnpm.updateConfig.ignoreDependencies

Update PrismarineJS Packages

Update to latest versions:

minecraft-data (update version twice in package.json)
mineflayer
minecraft-protocol
prismarine-block
prismarine-chunk
prismarine-item

Handle minecraft-protocol Patch

If the patch fails:

# 1. Remove patch from package.json patchedDependencies

# 2. Create patch directory
pnpm patch minecraft-protocol

# 3. Apply patch manually
cd /path/to/patch/dir
patch -p1 < [email protected]

# 4. Update the patch
pnpm patch-commit /path/to/patch/dir

Development Tips

Fast Development Reload

Press Y in-game to reload the application into the same world/server.

React Profiling

To enable React profiling:

Disable REACT_APP_PROFILING code first
Use React DevTools Profiler

Use the Debugger

VSCode has excellent debugging support. Use --no-sources flag for faster source map parsing.

Clear Cache

If things don’t work after upgrading dependencies:

rm -rf dist/

Production Testing

The same dist folder is used for dev and prod builds. Test production builds before deploying.

Testing Guidelines

Unit Tests

Location: **/*.test.ts files in src/ and renderer/

pnpm test-unit

We’re working to improve test coverage. Contributions of tests are very welcome!

Cypress E2E Tests

Location: cypress/ folder

# Terminal 1: Start test Minecraft server
pnpm test-mc-server

# Terminal 2: Start production build
pnpm prod-start

# Terminal 3: Run tests
pnpm test:cypress

To test with dev server (port 3000), update the Cypress configuration.

Pull Request Guidelines

Let us know what you’re working on (GitHub issue or Discord)
Test thoroughly before opening PR
Allow maintainer edits when opening the PR
Follow the workflow outlined above
Add tests if possible
Update documentation if needed

If CI fails on the next branch, feel free to use the latest commit from the release branch. We’ll update the base branch ASAP.

Getting Help

GitHub Issues: Report bugs or request features
Discord: Ask questions and discuss development
Documentation: Check existing docs and code comments

Code Style

The project uses ESLint for code style:

# Check for issues
pnpm lint

# Auto-fix issues
pnpm lint-fix

Key style points:

TypeScript for all new code
Follow existing patterns in the codebase
Comment complex logic
Use meaningful variable names

Useful Resources

Next Steps

Debugging - Learn debugging techniques
Proxy Setup - Set up development proxy
Docker - Use Docker for development

Happy coding! If you have any questions, feel free to ask on GitHub or Discord.

Get Started

Playing

Features

Advanced

Getting Started

Project Structure

1. Core (`src/`)

2. Renderer (`renderer/`)

3. Storybook (`.storybook/`)

Development Scripts

Common Commands

Testing

Production Build

Architecture Details

How Modules Work

Tasks Categories

1. Client-Side Logic (High Priority)

2. Three.js Renderer

3. Server-Side Logic

4. Frontend/UI

Development Workflow

Making Protocol Changes

Protocol Documentation

Generated Packet Files

Linking Dependencies Locally

Updating Dependencies

Development Tips

Testing Guidelines

Unit Tests

Cypress E2E Tests

Pull Request Guidelines

Getting Help

Code Style

Useful Resources

Next Steps

Build docs developers (and LLMs) love

Get Started

Playing

Features

Advanced

​Getting Started

​Project Structure

​1. Core (src/)

​2. Renderer (renderer/)

​3. Storybook (.storybook/)

​Development Scripts

​Common Commands

​Testing

​Production Build

​Architecture Details

​How Modules Work

​Tasks Categories

​1. Client-Side Logic (High Priority)

​2. Three.js Renderer

​3. Server-Side Logic

​4. Frontend/UI

​Development Workflow

​Making Protocol Changes

​Protocol Documentation

​Generated Packet Files

​Linking Dependencies Locally

​Updating Dependencies

​Development Tips

​Testing Guidelines

​Unit Tests

​Cypress E2E Tests

​Pull Request Guidelines

​Getting Help

​Code Style

​Useful Resources

​Next Steps

Build docs developers (and LLMs) love

Getting Started

Project Structure

1. Core (`src/`)

2. Renderer (`renderer/`)

3. Storybook (`.storybook/`)

Development Scripts

Common Commands

Testing

Production Build

Architecture Details

How Modules Work

Tasks Categories

1. Client-Side Logic (High Priority)

2. Three.js Renderer

3. Server-Side Logic

4. Frontend/UI

Development Workflow

Making Protocol Changes

Protocol Documentation

Generated Packet Files

Linking Dependencies Locally

Updating Dependencies

Development Tips

Testing Guidelines

Unit Tests

Cypress E2E Tests

Pull Request Guidelines

Getting Help

Code Style

Useful Resources

Next Steps