Running BlockAssist

Overview

Use the step-by-step guide below to run BlockAssist, train models, and start contributing to Gensyn's Testnet.

Logs

Use tail -f logs/[specific log].log to monitor progress, and ls logs to see options.

Running with Python

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

python run.py

python run.py

pyenv exec python run.py

HuggingFace Token

You will be asked to enter a Hugging Face API token.

Follow the instructions in this guide, and make sure the token has Write access.

Logging into Gensyn Testnet

The terminal will show a LOGIN section where the system:

• Requests accessibility permissions (approve these if prompted)

• Waits for user authentication data to be created

• Confirms successful login setup

Play Minecraft

Next, the terminal will display a START MINECRAFT section:

1. Prompts you to wait for two Minecraft windows to open (up to 5 minutes)

2. Do not close either Minecraft window manually. The app manages them.

1. Run tail -f logs/malmo.log in another terminal to monitor for errors.

2. Press ENTER when both Minecraft windows are open and ready.

Game Instructions

The objective is to construct the structure in front of you by adding or removing blocks. Each attempt to build is referred to as an "episode." The AI player learns from your actions as you continue to play.

Game Controls

• Click on the Minecraft window and press ENTER to start playing

• Break red blocks and place blocks where indicated

• Left click to break blocks & right click to place blocks

• Select tools/blocks by pressing number keys 1-9

• Use WASD keys to move around

• Press ESC when finished, then return to the terminal

Record an Episode

The terminal will show a STARTING EPISODE 0 section.

At this stage, the program:

• Waits for the mission to load in Minecraft

• Begins recording your gameplay with a progress bar and timer

• Press ENTER when finished to stop recording

Training Process

When the terminal displays the MODEL TRAINING section, BlockAssist begins training the AI model based on your recorded gameplay.

This process can take some time depending on your hardware performance, so keep the terminal window open until training completes. You’ll see progress updates and status indicators as the model trains.

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

Reviewing 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

You can see the details of the contract & transaction in the 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, but only after you've confirmed the transaction and model upload, or you may lose your training progress.

Testing & Contributing

Contributions to BlockAssist are welcome, whether through code improvements, testing, or documentation feedback.

The following tools and options help you maintain a [1] consistent and [2] privacy-respecting development environment.

Telemetry

Running the following command disables anonymous usage data for your session. Paste this in the same terminal before starting the app:

export DISABLE_TELEMETRY=1

To make this change permanent, add the same line to your ~/.zshrc.

Linting / Testing

This project uses Ruff to keep code tidy, which sorts imports and auto-fixes simple style issues.

How to run (from the project folder):

ruff check --select I --fix .

If you see ruff: command not found, install it once using this command:

pyenv exec pip install ruff