# Windows (WSL 2)

## Overview

This guide explains how to install and run BlockAssist v0.1.0 on Windows 10 or 11 using Windows Subsystem for Linux (WSL). It walks you through environment setup, dependency installation, authentication, and configuration for running the Minecraft interface through **VcXsrv**.

### Prerequisites

* Windows 10/11 with WSL 2 enabled
* Ubuntu 22.04 LTS (recommended) or another supported Linux distribution inside WSL
* At least 12 GB RAM (32 GB recommended)
* Git installed on both Windows and WSL
* A Hugging Face account with a [Write-access API token](https://docs.gensyn.ai/testnet/blockassist/hugging-face-guide)
* Gensyn Testnet account

{% hint style="success" %}
If you don't have a Testnet account, don't worry--you'll be prompted to create it automatically on your first log-in attempt.
{% endhint %}

#### Dependencies

* **Core:** Python 3.10 (via pyenv), Java 1.8.0\_152 (OpenJDK 8), Git
* **Display Server:** VcXsrv or another X Server for Windows
* **GPU Support (Optional):** CUDA and cuDNN for Nvidia GPUs

### Installation Steps

#### Step 1 — Clone the Repository

Open your WSL terminal and clone the BlockAssist repository:

```bash
git clone https://github.com/gensyn-ai/blockassist.git
```

Then, navigate to the directory.

```bash
cd blockassist
```

#### Step 2 — Install Core Dependencies

1. Run the setup script to install Java.

```bash
./setup.sh
```

2. Next, install and configure your Python environment:

```bash
curl -fsSL https://pyenv.run | bash
```

3. Configure `pyenv`:

```bash
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - bash)"
eval "$(pyenv virtualenv-init -)"
```

4. Reload your shell after configuring your Python environment using `source ~/.bashrc`.
5. Update your system and install build tools:

```bash
sudo apt update
sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev \
curl git libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
```

6. Install Python 3.10 and set it globally:

```bash
pyenv install 3.10.0
pyenv global 3.10.0
```

7. Install Python libraries: 

```
pip install psutil readchar rich
```

#### Step 3 — Configure Node.js and Yarn

1. Install Node Version Manager (NVM):

```bash
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
```

2. Load NVM and install Node LTS:

```bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
nvm install --lts
nvm alias default 'lts/*'
nvm use default
```

3. Enable Corepack and install Yarn:

```bash
corepack enable
corepack prepare yarn@stable --activate
node -v
npm -v
yarn -v
```

#### Step 4 — Optional GPU Setup (cuDNN)

If you have an Nvidia GPU, install cuDNN for acceleration. 

Use the appropriate installer for Ubuntu 22.04, then run:

```bash
sudo apt update
sudo apt install -y libcudnn9 libcudnn9-dev
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc
```

#### Step 5 — Verify Installation

You're now ready to create and activate a virtual environment:

```bash
python3 -m venv blockassist-venv
source blockassist-venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
pip install -e .

```

Confirm Malmo is detected:

```bash
python - <<'PY'
import pkgutil
print('malmo' in [m.name for m in pkgutil.iter_modules()])
PY
```

***

### Platform-Specific Notes

When launching VcXsrv on Windows, make sure you've enabled/disabled the following:

| Enable          | Disable        |
| --------------- | -------------- |
| Multi-Window    | Access Control |
| Start no client | Native OpenGL  |

Also, make sure to:&#x20;

* Set the display variable in WSL 2: `export DISPLAY=<WINDOWS_IP>:0`
* Test X11 forwarding with `xeyes`

If you see black screens or OpenGL crashes, enable software rendering:

```bash
export LIBGL_ALWAYS_SOFTWARE=1
export MESA_LOADER_DRIVER_OVERRIDE=llvmpipe
export LIBGL_ALWAYS_INDIRECT=1
export _JAVA_OPTIONS='-Xms512m -Xmx2g -Dorg.lwjgl.opengl.Display.allowSoftwareOpenGL=true'

```

### Authentication

{% stepper %}
{% step %}

### Navigate to the Directory

Enter `cd modal-login` and run `yarn install` followed by `yarn dev`.
{% endstep %}

{% step %}

### Go to LocalHost

Open a browser and go to `http://localhost:3000`, log in to your Gensyn Testnet account, and then stop the server with Ctrl+C.
{% endstep %}

{% step %}

### Activate your Environment

Return to the main directory and run `source blockassist-venv/bin/activate`.
{% endstep %}

{% step %}

### Start BlockAssist

To start BlockAssist, enter `python3 run.py`.

{% hint style="warning" %}
When prompted, enter your HuggingFace token.&#x20;
{% endhint %}
{% endstep %}
{% endstepper %}

### Troubleshooting

Here's a list of some common problems and quick fixes.&#x20;

| Issue                                      | Solution                                              |
| ------------------------------------------ | ----------------------------------------------------- |
| Minecraft window not opening               | Check `DISPLAY` variable and VcXsrv configuration     |
| Black screen or OpenGL crash               | Enable software rendering                             |
| “pyenv: command not found”                 | Reinitialize `pyenv` and reload shell                 |
| “malmo.log not found”                      | Reinstall using `pip install -e .`                    |
| Startup freezes at 100%                    | Wait for about one minute, then press `ENTER`         |
| “Minecraft unexpectedly crashed on launch” | Edit scripts/run\_malmo.sh to include `--timeout 300` |

{% hint style="success" %}
If you need additional support, you can [open a ticket](https://github.com/gensyn-ai/blockassist/issues) or [visit our Discord.](https://discord.com/invite/gensyn)&#x20;
{% endhint %}