Getting started

If you know your way around a code editor and a CLI, or if you are planning on running BlockAssist on Linux, follow the instructions below or in the repo's README file.

If you're not as familiar with running code, follow this guide on how to run BlockAssist with Cursor AI guiding you through the process.

Installation (macOS)

Note: You only need to run these once per computer, and you don't need to have Minecraft installed.

Step 1: Clone and enter repo

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

Step 2: Install Java 1.8.0_152

./setup.sh

Step 3: Install pyenv

Note: This step assumes Homebrew is installed on your Mac

brew update
brew install pyenv

Step 4: Install Python 3.10

pyenv install 3.10

Step 5: Install psutil and readchar

pyenv exec pip install psutil readchar

Installation (Linux)

Note: You only need to run these once per computer, and you don't need to have Minecraft installed.

Step 1: Clone and enter repo

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

Step 2: Install Java 1.8.0_152

./setup.sh

Step 3: Install pyenv

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

NOTE: Follow the instructions pyenv gives about adding it to your shell!

Step 4: Install Python 3.10

sudo apt update
sudo apt install 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 # Dependencies for Python installation
pyenv install 3.10

Step 5: Install psutil and readchar

pip install psutil readchar

Run BlockAssist

Use tail -f logs/[specific log].log to monitor progress. ls logs to see options. Note, when asked to press ENTER, sometimes you need to do this a few times.

Run with Python

• On Mac: pyenv exec python run.py

• On Linux: python run.py

The program will install various dependencies as required. Follow any instructions and approve all asks.

Huggingface Token

You will be asked to enter a Hugging Face API token. Follow the instructions here to generate one. It will need Write access.

Gensyn Testnet login

You will be prompted to log in through the browser. If you have previously logged in, it will skip this step. Otherwise, log in using the browser window that just opened.

Play Minecraft

Once the Minecraft windows have loaded, the Python script will ask you to press ENTER.

Go to the first Minecraft window that opened (the other one will be minimised if you are running on Mac). Click the window. Press ENTER to have it capture your inputs. Complete the structure in-game, then go back to your terminal and hit ENTER to end the session.

Training

A model will now be trained and submitted to Hugging Face and Gensyn's smart contract.

Review logs

If you reach this stage in the logging window, and can see a transaction in the block explorer, then submissions have worked.

Logging window:

[2025-07-28 05:03:48,955][blockassist.globals][INFO] - Successfully uploaded model to HuggingFace: h-grieve/blockassist-bc-bellowing_pouncing_horse_1753675374 with size 20.00 MB

Gensyn Testnet block explorer:

huggingFaceID
string
false
h-grieve/blockassist-bc-bellowing_pouncing_horse_1753675374

The program will then end. Please close any minecraft windows if they remain open.