CraftGround

https://yhs0602.github.io/CraftGround
Admin
CraftGround provides a lightweight and customizable environment for reinforcement learning...
Tokens:38,621
Snippets:311
Trust Score:9.7
Update:3 days ago
Show doc for...
Tokens:
Raw
### Start Xvfb Virtual Display

Source: https://yhs0602.github.io/CraftGround/installation/headless.html

Install and launch Xvfb with GLX and RENDER extensions.

```bash
sudo apt install xvfb
Xvfb :2 -screen 0 1024x768x24 +extension GLX -ac +extension RENDER & 
export DISPLAY=:2
VGL_DISPLAY=:0 vglrun /opt/VirtualGL/bin/glxspheres64
```

--------------------------------

### Install gfortran

Source: https://yhs0602.github.io/CraftGround/blog/install_minerl.html

Install gfortran if it is not found during installation.

```bash
sudo apt install gfortran
```

--------------------------------

### Install Xvfb

Source: https://yhs0602.github.io/CraftGround/installation/headless.html

Install Xvfb to emulate a 2D X server.

```bash
sudo apt install xvfb
```

--------------------------------

### Install CraftGround Development Version

Source: https://yhs0602.github.io/CraftGround

Install the latest development version directly from the GitHub repository.

```bash
pip install git+https://github.com/yhs0602/CraftGround.git@dev
```

--------------------------------

### Install CraftGround on Ubuntu

Source: https://yhs0602.github.io/CraftGround

Install system dependencies and the craftground package on Ubuntu-based systems.

```bash
sudo apt-get update
sudo apt-get install -y openjdk-21-jdk python3-pip git \
    libgl1-mesa-dev libegl1-mesa-dev libglew-dev \
    libglu1-mesa-dev xorg-dev libglfw3-dev xvfb
apt-get clean
pip3 install --upgrade pip
pip3 install cmake # You need latest cmake, not the one provided by apt-get
pip3 install craftground
```

--------------------------------

### Install VirtualGL

Source: https://yhs0602.github.io/CraftGround/installation/headless.html

Download and install the VirtualGL package.

```bash
sudo apt install virtualgl
wget https://sourceforge.net/projects/virtualgl/files/3.1/virtualgl_3.1_amd64.
deb/download
mv download vgl3.1.deb
sudo dpkg -i vgl3.1.deb
```

--------------------------------

### Example Exploration with Stable Baselines3

Source: https://yhs0602.github.io/CraftGround/integration_sb3.html

A comprehensive example showing how to initialize a W&B run, configure the CraftGround environment with wrappers, and train a PPO agent.

```python
import os.path

import wandb
from craftground import craftground
from craftground.wrappers.action import ActionWrapper, Action
from craftground.wrappers.fast_reset import FastResetWrapper
from craftground.wrappers.time_limit import TimeLimitWrapper
from craftground.wrappers.vision import VisionWrapper
from stable_baselines3 import PPO
from stable_baselines3.common.monitor import Monitor
from stable_baselines3.common.vec_env import VecVideoRecorder, DummyVecEnv
from wandb.integration.sb3 import WandbCallback
from craftground.craftground.screen_encoding_modes import ScreenEncodingMode
from check_vglrun import check_vglrun

from get_device import get_device

current_path = os.path.dirname(os.path.abspath(__file__))
map_path = os.path.join(current_path, "custom_structure.nbt")

def example_exploration():
    group_name = "example-exploration"
    run = wandb.init(
        # set the wandb project where this run will be logged
        project="craftground-sb3",
        entity="your-name",
        # track hyperparameters and run metadata
        group=group_name,
        sync_tensorboard=True,  # auto-upload sb3's tensorboard metrics
        monitor_gym=True,  # auto-upload the videos of agents playing the game
        save_code=True,  # optional
    )
    size_x = 114
    size_y = 64
    base_env, sound_list = (
        craftground.make(
            port=8001,
            initialInventoryCommands=[],
            verbose=False,
            initialPosition=[5, 5, 5],  # nullable
            initialMobsCommands=[],
            imageSizeX=size_x,
            imageSizeY=size_y,
            visibleSizeX=size_x,
            visibleSizeY=size_y,
            seed=12345,  # nullable
            allowMobSpawn=False,
            alwaysDay=True,
            alwaysNight=False,
            initialWeather="clear",  # nullable
            isHardCore=False,
            isWorldFlat=True,  # superflat world
            obs_keys=[],  # No sound subtitles
            miscStatKeys=[],  # No stats
            initialExtraCommands=[
                "time set noon",
                "place template minecraft:custom_structure 0 0 0",
                "tp @p 3 1 1 -90 0",
            ],  # x y z yaw pitch
            isHudHidden=True,
            render_action=False,
            render_distance=5,
            simulation_distance=5,
            structure_paths=[
                map_path,
            ],
            no_pov_effect=True,
            screen_encoding_mode=ScreenEncodingMode.RAW,
            use_vglrun=check_vglrun(),
        ),
        [],
    )
    env = FastResetWrapper(
        TimeLimitWrapper(
            ActionWrapper(
                VisionWrapper(
                    base_env,
                    x_dim=size_x,
                    y_dim=size_y,
                ),
                enabled_actions=[
                    Action.FORWARD,
                    Action.TURN_LEFT,
                    Action.TURN_RIGHT,
                ],
            ),
            max_timesteps=20000,
        ),
    )
    env = DummyVecEnv([lambda: env])
    env = Monitor(env)
    env = VecVideoRecorder(
        env,
        f"videos/{run.id}",
        record_video_trigger=lambda x: x % 20000 == 0,
        video_length=20000,
    )

    model = PPO(
        "CnnPolicy",
        env,
        verbose=1,
        device=get_device(),
        tensorboard_log=f"runs/{run.id}",
        gae_lambda=0.99,
        ent_coef=0.005,
        n_steps=512,
    )

    try:
        model.learn(
            total_timesteps=6000000,
            callback=[
                WandbCallback(
                    gradient_save_freq=500,
                    model_save_path=f"models/{run.id}",
                    verbose=2,
                ),
            ],
        )
        model.save(f"{group_name}.ckpt")
        run.finish()
    finally:
        base_env.terminate()


if __name__ == "__main__":
    example_exploration()
```

--------------------------------

### Install OpenBLAS

Source: https://yhs0602.github.io/CraftGround/blog/install_minerl.html

Install libopenblas-dev if OpenBLAS is not found.

```bash
sudo apt install libopenblas-dev
```

--------------------------------

### Linux and macOS Installation

Source: https://yhs0602.github.io/CraftGround/installation

Creates a new Conda environment, installs required dependencies including the latest CMake, and installs CraftGround.

```bash
conda create -n exp_craftground python=3.11
conda activate exp_craftground
conda install -c conda-forge openjdk=21 cmake glew libpng zlib opengl flite
pip install craftground
```

--------------------------------

### Install JDK 8 via APT

Source: https://yhs0602.github.io/CraftGround/blog/install_minerl.html

Install the required JDK 8 using apt.

```bash
sudo apt install openjdk-8-jdk
```

--------------------------------

### Install CraftGround via Conda

Source: https://yhs0602.github.io/CraftGround

Create a new environment and install necessary dependencies and the craftground package.

```bash
conda create -n my_experiment_env python=3.11
conda activate my_experiment_env
conda install conda-forge::openjdk=21 conda-forge::cmake conda-forge::glew-dev conda-forge::libpng conda-forge::libzlib conda-forge::libopengl conda-forge::libflite
pip install craftground
```

--------------------------------

### Install formatters on macOS

Source: https://yhs0602.github.io/CraftGround/develop

Use Homebrew to install ktlint, clang-format, and google-java-format.

```bash
brew install ktlint clang-format google-java-format
```

--------------------------------

### SoundWrapper Usage Example

Source: https://yhs0602.github.io/CraftGround/wrappers.html

Example of initializing the SoundWrapper with specific sound lists and coordinate dimensions, followed by the resulting observation values.

```python
env = SoundWrapper(
    env,
    sound_list=[
        "minecraft:entity.zombie.ambient",
        "minecraft:entity.zombie.death",
        "minecraft:entity.zombie.hurt",
    ],
    zeroing_sound_list=["subtitles.entity.player.hurt"],
    coord_dim=3,
)
```

```text
[
    0.2, 0.2, 0.2 # zombie.ambient
    0.5, 0.5, 0.5 # zombie.death
    0.8, 0.8, 0.8 # zombie.hurt
    1.0 # player.hurt
    0.5, 0.87 # Cos and Sin of agent's yaw
]
```

--------------------------------

### Install formatters on Ubuntu / Debian

Source: https://yhs0602.github.io/CraftGround/develop

Download and run the LLVM script, install clang-format-19, and create a symbolic link.

```bash
wget https://apt.llvm.org/llvm.sh
sudo ./llvm.sh 19
sudo apt install clang-format-19
sudo ln -s /usr/bin/clang-format-19 /usr/bin/clang-format
```

--------------------------------

### Minimal CraftGround PPO Implementation

Source: https://yhs0602.github.io/CraftGround/configuration/example_code.html

This script includes utility functions for environment setup, a custom TreeWrapper to map actions for PPO, and the main ppo_check function to initialize the training environment and model.

```python
import argparse
import sys
import time
from craftground.screen_encoding_modes import ScreenEncodingMode
import wandb
from craftground.wrappers.vision import VisionWrapper

try:
    from craftground.minecraft import no_op_v2
except ImportError:
    from craftground.environment.action_space import no_op_v2
from stable_baselines3.common.vec_env import DummyVecEnv, VecVideoRecorder
from stable_baselines3 import PPO
from wandb.integration.sb3 import WandbCallback
from stable_baselines3.common import on_policy_algorithm
import platform
from craftground.initial_environment_config import DaylightMode
import gymnasium as gym
from typing import SupportsFloat, Any
from gymnasium.core import WrapperActType, WrapperObsType
import craftground
from craftground import InitialEnvironmentConfig, ActionSpaceVersion
import torch

# Utility function for headless environment setup
def check_vglrun():
    from shutil import which

    return which("vglrun") is not None

# Utility function to get the accelerator device
def get_device(dev_num: int = 0) -> torch.device:
    if torch.cuda.is_available():
        device = torch.device(f"cuda:{dev_num}")
        torch.cuda.empty_cache()
    elif torch.backends.mps.is_built():
        device = torch.device("mps")
    else:
        device = torch.device("cpu")
    return device

# Utility function to create the CraftGround environment
def make_craftground_env(
    port: int,
    width: int,
    height: int,
    screen_encoding_mode: ScreenEncodingMode,
    verbose_python: bool = False,
    verbose_gradle: bool = False,
    verbose_jvm: bool = False,
) -> gym.Env:
    return craftground.make(
        port=port,
        initial_env_config=InitialEnvironmentConfig(
            image_width=width,
            image_height=height,
            hud_hidden=False,
            render_distance=11,
            screen_encoding_mode=screen_encoding_mode,
        ).set_daylight_cycle_mode(DaylightMode.ALWAYS_DAY),
        action_space_version=ActionSpaceVersion.V2_MINERL_HUMAN,
        use_vglrun=check_vglrun(),
        verbose_python=verbose_python,
        verbose_gradle=verbose_gradle,
        verbose_jvm=verbose_jvm,
    )

# A wrapper that converts the dictionary action space to a multidiscrete action space, to be used with stable-baselines3's PPO.
class TreeWrapper(gym.Wrapper):
    def __init__(self, env):
        self.env = env
        super().__init__(env)
        self.action_space = gymnasium.spaces.MultiDiscrete(
            [
                2,  # forward
                2,  # back
                2,  # left
                2,  # right
                2,  # jump
                2,  # sneak
                2,  # sprint
                2,  # attack
                25,  # pitch
                25,  # yaw
            ]
        )

    def step(
        self, action: WrapperActType
    ) -> tuple[WrapperObsType, SupportsFloat, bool, bool, dict[str, Any]]:
        action_v2 = no_op_v2()
        # print(f"{action=}")
        action_v2["forward"] = action[0]
        action_v2["back"] = action[1]
        action_v2["left"] = action[2]
        action_v2["right"] = action[3]
        action_v2["jump"] = action[4]
        action_v2["sneak"] = action[5]
        action_v2["sprint"] = action[6]
        action_v2["attack"] = action[7]
        action_v2["camera_pitch"] = (action[8] - 12) * 15
        action_v2["camera_yaw"] = (action[9] - 12) * 15
        obs, reward, terminated, truncated, info = self.env.step(action_v2)
        return obs, reward, terminated, truncated, info

# The main function that runs the PPO algorithm with the CraftGround environment
def ppo_check(
    run: wandb.Run,
    screen_encoding_mode: ScreenEncodingMode,
    vision_width: int,
    vision_height: int,
    port: int,
    device: str,
    max_steps: int = 10000,
):
    env = make_craftground_env(
        port=port,
        width=vision_width,
        height=vision_height,
        screen_encoding_mode=screen_encoding_mode,
    )
    # VisionWrapper selects only the visual information from the observation space.
    env = VisionWrapper(env, x_dim=vision_width, y_dim=vision_height)
    # Task specific wrappers
    env = TreeWrapper(env)
    env = DummyVecEnv([lambda: env])
    # Record video every 2000 steps and save the video
    env = VecVideoRecorder(
        env,
        f"videos/{run.id}",
        record_video_trigger=lambda x: x % 2000 == 0,
        video_length=2000,
    )
    model = PPO(
        "CnnPolicy",
        env,
        verbose=1,
        device=device,
        tensorboard_log=f"runs/{run.id}",
        gae_lambda=0.99,
        ent_coef=0.005,
        n_steps=512,
    )
```

--------------------------------

### Install VirtualGL

Source: https://yhs0602.github.io/CraftGround/installation/headless.html

Download and install the VirtualGL Debian package.

```bash
wget https://github.com/VirtualGL/virtualgl/releases/download/3.1.3/virtualgl_3.1.3_amd64.deb
sudo dpkg -i virtualgl_3.1.3_amd64.deb
```

--------------------------------

### Install VirtualGL dependencies

Source: https://yhs0602.github.io/CraftGround/installation/headless.html

Install required mesa and X11 libraries before setting up VirtualGL.

```bash
sudo apt install libegl1-mesa
sudo apt install libxtst6
```

--------------------------------

### Install MineRL 0.4.4 with compilation steps

Source: https://yhs0602.github.io/CraftGround/blog/install_minerl.html

Complete installation sequence for MineRL 0.4.4, including creating a conda environment, installing dependencies, downloading and patching the source, and running an experiment. Requires gcc-10/g++-10 and a manual edit to build.gradle.

```bash
conda create -n exp_minerl044 python=3.11
conda activate exp_minerl044
conda install conda-forge::openjdk=8 
pip install setuptools==65.5.0 pip==21 wheel==0.38.0
pip install gym==0.19.0
pip install --upgrade pip
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt update
sudo apt install -y libxml2-dev libxslt1-dev gfortran libopenblas-dev software-properties-common
# Ensure you have the latest version of gcc:
# To check the version of gcc, run `gcc --version`
sudo apt-get install gcc-10 g++-10
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 120
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-10 120
OPENSSL_ROOT_DIR=$CONDA_PREFIX pip download --no-binary :all: minerl==0.4.4
tar -xvf minerl-0.4.4.tar.gz
cd minerl-0.4.4
# remove gym line from requirements.txt
pip install -r requirements.txt
# Edit minerl-0.4.4/minerl/Malmo/Minecraft/build.gradle:L19 based on
# https://github.com/MineDojo/MineDojo/issues/113#issuecomment-1908997704
# classpath('MixinGradle-dcfaf61:MixinGradle:dcfaf61'){ // 0.6
# Add repository maven to the build.gradle
#         maven { url 'file:file:/absolute-path/to/that/repo's/parent' }
pip install .
pip install wandb tensorboard moviepy stable-baselines3
pip install --upgrade git+https://github.com/DLR-RM/stable-baselines3.git # To ensure correct video rendering
vglrun python experiments/minerl044.py --image_width 64x64 --load simulation
```

--------------------------------

### Install CMake via Pip

Source: https://yhs0602.github.io/CraftGround/blog/install_minerl.html

Install the latest version of cmake using pip.

```bash
pip install --upgrade cmake
```

--------------------------------

### Full implementation of structure loading with Stable Baselines3

Source: https://yhs0602.github.io/CraftGround/configuration/custom_structure.html

A complete example demonstrating the integration of custom structures, environment wrappers, and Stable Baselines3 training with WandB logging.

```python
import os.path

import wandb
from craftground import craftground
from craftground.wrappers.action import ActionWrapper, Action
from craftground.wrappers.fast_reset import FastResetWrapper
from craftground.wrappers.vision import VisionWrapper
from craftground.craftground.screen_encoding_modes import ScreenEncodingMode
from stable_baselines3 import A2C
from stable_baselines3.common.monitor import Monitor
from stable_baselines3.common.vec_env import VecVideoRecorder, DummyVecEnv
from wandb.integration.sb3 import WandbCallback


def structure_any():
    run = wandb.init(
        # set the wandb project where this run will be logged
        project="craftground-sb3",
        entity="jourhyang123",
        # track hyperparameters and run metadata
        group="structure-a2c-vision",
        sync_tensorboard=True,  # auto-upload sb3's tensorboard metrics
        monitor_gym=True,  # auto-upload the videos of agents playing the game
        save_code=True,  # optional    save_code=True,  # optional
    )
    size_x = 114
    size_y = 64
    base_env, sound_list = (
        craftground.make(
            port=8001,
            initialInventoryCommands=[],
            verbose=True,
            initialPosition=[5, 5, 5],  # nullable
            initialMobsCommands=[],
            imageSizeX=size_x,
            imageSizeY=size_y,
            visibleSizeX=size_x,
            visibleSizeY=size_y,
            seed=12345,  # nullable
            allowMobSpawn=False,
            alwaysDay=True,
            alwaysNight=False,
            initialWeather="clear",  # nullable
            isHardCore=False,
            isWorldFlat=True,  # superflat world
            obs_keys=[],  # No sound subtitles
            miscStatKeys=[],  # No stats
            initialExtraCommands=[
                "place template minecraft:portable_maze 0 0 0",
                "tp @p 5 5 5 -90 0",
            ],  # x y z yaw pitch
            isHudHidden=True,
            render_action=True,
            render_distance=5,
            simulation_distance=5,
            structure_paths=[
                os.path.abspath("portable_maze.nbt"),
            ],
            no_pov_effect=True,
            screen_encoding_mode=ScreenEncodingMode.RAW,
            use_vglrun=False, # check_vglrun(),
        ),
        [],
    )
    env = FastResetWrapper(
        ActionWrapper(
            VisionWrapper(
                base_env,
                x_dim=size_x,
                y_dim=size_y,
            ),
            enabled_actions=[
                Action.FORWARD,
                Action.TURN_LEFT,
                Action.TURN_RIGHT,
            ],
        ),
    )
    env = Monitor(env)
    env = DummyVecEnv([lambda: env])
    env = VecVideoRecorder(
        env,
        f"videos/{run.id}",
        record_video_trigger=lambda x: x % 4000 == 0,
        video_length=400,
    )
    model = A2C(
        "CnnPolicy", env, verbose=1, tensorboard_log=f"runs/{run.id}"
    )

    model.learn(
        total_timesteps=1000,
        callback=WandbCallback(
            gradient_save_freq=100,
            model_save_path=f"models/{run.id}",
            verbose=2,
        ),
    )
    # model.save("dqn_sound_husk")
    run.finish()
    base_env.terminate()


if __name__ == "__main__":
    structure_any()

```

--------------------------------

### Structure usage example

Source: https://yhs0602.github.io/CraftGround/configuration/api.html

Demonstrates how to instantiate a structure, add various geometric shapes, and save the result to an NBT file.

```python
if __name__ == "__main__":
    structure = Structure()
    
    structure.set_cuboid(0, 0, 0, 10, 10, 10, "minecraft:stone")
    structure.set_walls(15, 0, 0, 25, 10, 10, "minecraft:diamond_ore")
    structure.set_line(30, 0, 0, 40, 10, 10, "minecraft:gold_ore")
    structure.set_filled_sphere(55, 5, 5, 5, "minecraft:glass")
    structure.set_hollow_sphere(75, 5, 5, 3, 5, "minecraft:torch")
    structure.set_cylinder(95, 0, 5, 5, 10, "minecraft:gold_block")
    structure.set_hollow_cylinder(115, 0, 5, 5, 10, 10, "minecraft:oak_planks")
    
    structure.save("debug_structure.nbt")
```

--------------------------------

### Start Xvfb buffer

Source: https://yhs0602.github.io/CraftGround/installation/headless.html

Initialize the Xvfb display buffer and set the DISPLAY environment variable.

```bash
Xvfb :2 -screen 0 1024x768x24 +extension GLX -ac +extension RENDER &
export DISPLAY=:2
```

--------------------------------

### Setup Development Environment with Conda

Source: https://yhs0602.github.io/CraftGround/develop

Creates and configures a Conda environment with the necessary dependencies for CraftGround development on Linux.

```bash
conda create --name craftground python=3.11
conda activate craftground
conda install gymnasium Pillow numpy protobuf typing_extensions psutil pytorch ninja build cmake
conda install -c conda-forge openjdk=21 libgl-devel
conda install glew
python -m build
```

--------------------------------

### Install GCC 10 on Ubuntu

Source: https://yhs0602.github.io/CraftGround/blog/install_minerl.html

Update the repository and install GCC 10 and G++ 10 to meet NumPy and SciPy requirements.

```bash
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt update
sudo apt install -y software-properties-common
sudo apt-get install gcc-10 g++-10
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 120
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-10 120
```

--------------------------------

### Install coverage and pytest dependencies

Source: https://yhs0602.github.io/CraftGround/develop

Install the required testing and coverage reporting tools using pip.

```bash
python -m pip install coverage pytest
```

--------------------------------

### Install JDK 8 via Conda

Source: https://yhs0602.github.io/CraftGround/blog/install_minerl.html

Install the required JDK 8 using conda.

```bash
conda install conda-forge::openjdk=8
```

--------------------------------

### Install MineRL 1.0.0

Source: https://yhs0602.github.io/CraftGround/blog/install_minerl.html

Simplified installation for MineRL 1.0.0 using conda and pip. Includes optional CUDA and Apple device dependencies, and runs an experiment with vglrun.

```bash
conda create -n exp_minerl100 python=3.11
conda activate exp_minerl100
conda install conda-forge::openjdk=8
pip install git+https://github.com/minerllabs/minerl
pip install wandb tensorboard moviepy stable-baselines3
pip install --upgrade git+https://github.com/DLR-RM/stable-baselines3.git # To ensure correct video rendering
conda install -c anaconda cudnn # for ppo
# On cuda devices
pip install jax[cuda]
# On apple devices
pip install jax-metal
vglrun python experiments/minerl100_exp.py --image_width 64x64 --load simulation
```

--------------------------------

### Install patched MineRL from GitHub

Source: https://yhs0602.github.io/CraftGround/blog/install_minerl.html

Alternative installation command for MineRL using a patched version from a GitHub repository, intended for MacOS compatibility.

```bash
pip install git+https://github.com/yhs0602/minerl  
```

--------------------------------

### Check Wayland session status

Source: https://yhs0602.github.io/CraftGround/installation/headless.html

Verify if the current session is using Wayland. Proceed with installation only if nothing is printed.

```bash
echo $WAYLAND_DISPLAY
echo $XDG_SESSION_TYPE
ps aux | grep -E 'weston|sway'
```

--------------------------------

### Upgrade Protobuf Runtime

Source: https://yhs0602.github.io/CraftGround/develop

Resolves google.protobuf.runtime_version.VersionError by upgrading the installed protobuf package.

```bash
pip install --upgrade protobuf
```

--------------------------------

### Configure VirtualGL for GPU access

Source: https://yhs0602.github.io/CraftGround/blog/install_minerl.html

Commands to install and configure VirtualGL for GPU usage in headless environments.

```bash
echo $WAYLAND_DISPLAY
echo $XDG_SESSION_TYPE
ps aux | grep -E ’weston|sway’
sudo apt install virtualgl
wget https://sourceforge.net/projects/virtualgl/files/3.1/virtualgl_3.1_amd64.
deb/download
mv download vgl3.1.deb
sudo dpkg -i vgl3.1.deb
sudo vglserver_config
# During configuration, select the option to install both GLX and EGL and adjust device permissions as required
# In case you meed the following error, run the following command
# modprobe: FATAL: Module nvidia_drm is in use. You must execute modprobe -r nvidia_uvm nvidia_drm nvidia_modeset nvidia’ with the display manager stopped in order for the new device permission settings to become effective.
sudo systemctl stop gdm
sudo modprobe -r nvidia_uvm nvidia_drm nvidia_modeset nvidia
# If you meet modprobe: FATAL: Module nvidia_drm is in use.
sudo lsof /dev/nvidia*
pkill <pid>
# Restart the display manager
sudo modprobe nvidia_uvm nvidia_drm nvidia_modeset nvidia
sudo systemctl restart gdm
# Install Xvfb
sudo apt install xvfb
Xvfb :2 -screen 0 1024x768x24 +extension GLX -ac +extension RENDER & 
export DISPLAY=:2
VGL_DISPLAY=:0 vglrun /opt/VirtualGL/bin/glxspheres64
sudo nvidia-xconfig --query-gpu-info
sudo nvidia-xconfig -a --allow-empty-initial-configuration \
--use-display-device=None --virtual=1920x1200 \
--busid PCI:<BusID>
sudo systemctl restart gdm
VGL_DISPLAY=:0 vglrun /opt/VirtualGL/bin/glxspheres64
# OpenGL Renderer: NVIDIA GeForce RTX 3090/PCIe/SSE2.
```

--------------------------------

### Set initialExtraCommands for environment setup

Source: https://yhs0602.github.io/CraftGround/configuration/custom_structure.html

The initialExtraCommands parameter allows you to execute Minecraft commands upon environment initialization, such as setting time, placing templates, or applying effects.

```python
initialExtraCommands=[
    "time set noon",
    "place template minecraft:hmaze1_colored 0 0 0",
    "tp @p 3 1 1 -90 0",
    "effect give @p minecraft:speed infinite 2 true",  # speed effect, particle hidden
]

```

--------------------------------

### Run a Basic Reinforcement Learning Experiment

Source: https://yhs0602.github.io/CraftGround

Initialize the CraftGround environment and train an A2C model using stable-baselines3.

```python
from craftground import craftground
from stable_baselines3 import A2C

# Initialize environment
env = craftground.make(port=8023, isWorldFlat=True, ...)

# Train model
model = A2C("MlpPolicy", env, verbose=1)
model.learn(total_timesteps=10000)
model.save("a2c_craftground")
```

--------------------------------

### craftground.make

Source: https://yhs0602.github.io/CraftGround/lidar_feature.html

Creates an environment instance with the given initial environment configuration, including Lidar settings.

```APIDOC
## craftground.make

### Description
Creates an environment instance with the given initial environment configuration, including Lidar settings.

### Parameters
- **initial_env_config** (InitialEnvironmentConfig) - Required - Configuration object that includes LidarConfig.

### Returns
- **env** - The environment instance.

### Example
```python
import craftground
from craftground import LidarConfig

lidar_config = LidarConfig(
    horizontal_rays=32,
    max_distance=100.0
)

initial_env = craftground.InitialEnvironmentConfig(
    lidar_config=lidar_config
)

env = craftground.make(initial_env_config=initial_env)
```
```

--------------------------------

### Backup xorg.conf

Source: https://yhs0602.github.io/CraftGround/installation/headless.html

Create a backup of the current X11 configuration file.

```bash
sudo cp /etc/X11/xorg.conf /etc/X11/xorg.conf.bak
```

--------------------------------

### Install CMake via Conda

Source: https://yhs0602.github.io/CraftGround/blog/install_minerl.html

Install the latest version of cmake using conda.

```bash
conda install cmake
```

--------------------------------

### Configure VirtualGL

Source: https://yhs0602.github.io/CraftGround/installation/headless.html

Run the interactive configuration utility for VirtualGL.

```bash
sudo vglserver_config
```

--------------------------------

### Run tests with coverage reporting

Source: https://yhs0602.github.io/CraftGround/develop

Build the project, link the generated shared libraries to the source directory, and execute the test suite with coverage tracking.

```bash
cd build
cmake ..
cmake --build .
cd ..
ln -s build/*.dylib craftground/src/
ln -s build/*.so craftground/src/
ln -s build/*.pyd craftground/src/
PYTHONPATH=./build:src coverage run --source=src/craftground -m pytest tests/python/unit/
coverage report
```

--------------------------------

### Upgrade pip for build dependencies

Source: https://yhs0602.github.io/CraftGround/blog/install_minerl.html

Upgrade pip to resolve hangs during the installation of build dependencies.

```bash
pip install --upgrade pip
```

--------------------------------

### Initialize WandB and Execute PPO

Source: https://yhs0602.github.io/CraftGround/configuration/example_code.html

Initializes the WandB project and triggers the ppo_check function with specific environment and vision parameters.

```python
if __name__ == "__main__":
    # Initialize wandb
    run = wandb.init(project="craftground", entity="your_entity")
    # Run the PPO algorithm
    ppo_check(
        run=run,
        screen_encoding_mode=ScreenEncodingMode.RAW,
        vision_width=64,
        vision_height=64,
        port=8023,
        device=get_device(),
        max_steps=10000,
    )
```

--------------------------------

### Check CMake Version

Source: https://yhs0602.github.io/CraftGround/installation

Verifies the currently installed version of CMake. Expect version 3.21.0 or later.

```bash
cmake --version
```

--------------------------------

### Configure NVIDIA X Server

Source: https://yhs0602.github.io/CraftGround/installation/headless.html

Query GPU info and configure the X server for headless operation.

```bash
sudo nvidia-xconfig --query-gpu-info
sudo nvidia-xconfig -a --allow-empty-initial-configuration \
--use-display-device=None --virtual=1920x1200 \
--busid PCI:<BusID>
sudo systemctl restart gdm
VGL_DISPLAY=:0 vglrun /opt/VirtualGL/bin/glxspheres64
```

--------------------------------

### Generate proto files using dev_tools.sh

Source: https://yhs0602.github.io/CraftGround/develop

Source the development tools script and execute the generate_proto function.

```bash
source ./dev_tools.sh
generate_proto
```

--------------------------------

### Build Gradle Project

Source: https://yhs0602.github.io/CraftGround/develop

Builds the C++ and JVM components of the Minecraft environment using Gradle.

```bash
cd src/craftground/MinecraftEnv
./gradlew build
```

--------------------------------

### Run formatters manually

Source: https://yhs0602.github.io/CraftGround/develop

Execute clang-format, google-java-format, and ktlint directly on project files.

```bash
git ls-files -- '*.h' '*.cpp' '*.mm' | xargs clang-format -i
git ls-files -- '*.java' -z | xargs -0 -P 4 google-java-format -i
ktlint '!**/com/kyhsgeekcode/minecraftenv/proto/**' --format
```

--------------------------------

### Multi-Layer 3D Scanning Configuration

Source: https://yhs0602.github.io/CraftGround/lidar_feature.html

Configures a 3D Lidar setup with multiple vertical layers, similar to a Velodyne sensor.

```python
# 3D Lidar configuration (like Velodyne)
lidar_config = LidarConfig(
    horizontal_rays=64,      # 64 rays per layer
    max_distance=100.0,
    vertical_rays=16,        # 16 vertical layers
    vertical_fov=30.0        # -15° to +15° vertical coverage
)
```

--------------------------------

### InitialEnvironmentConfig Constructor

Source: https://yhs0602.github.io/CraftGround/configuration/initial_environment.html

Creates an InitialEnvironmentConfig instance with parameters to configure the Minecraft environment for reinforcement learning or simulation tasks.

```APIDOC
## InitialEnvironmentConfig Constructor

### Description
Initializes a new instance of the InitialEnvironmentConfig class with the specified configuration parameters.

### Parameters
- **image_width** (int) - Optional - Width of the rendered image. Default: 640.
- **image_height** (int) - Optional - Height of the rendered image. Default: 360.
- **gamemode** (GameMode) - Optional - Game mode (Survival, Hardcore, Creative). Default: GameMode.SURVIVAL.
- **difficulty** (Difficulty) - Optional - Difficulty level (Peaceful, Easy, Normal, Hard). Default: Difficulty.NORMAL.
- **world_type** (WorldType) - Optional - Type of world generation (Default, Superflat, Large Biomes, Amplified, Single Biome). Default: WorldType.DEFAULT.
- **world_type_args** (str) - Optional - Additional arguments for world type settings. Default: "".
- **seed** (str) - Optional - World seed for deterministic world generation. Default: "".
- **generate_structures** (bool) - Optional - Whether to generate structures like villages and dungeons. Default: True.
- **bonus_chest** (bool) - Optional - Whether to spawn a bonus chest at the start. Default: False.
- **datapack_paths** (List[str]) - Optional - Paths to custom datapacks to load. Default: None.
- **initial_extra_commands** (List[str]) - Optional - Commands executed at world initialization. Default: None.
- **killed_stat_keys** (List[str]) - Optional - Statistics keys related to player kills. Default: None.
- **mined_stat_keys** (List[str]) - Optional - Statistics keys related to blocks mined. Default: None.
- **misc_stat_keys** (List[str]) - Optional - Other relevant player statistics keys. Default: None.
- **surrounding_entity_distances** (List[int]) - Optional - Distances for tracking surrounding entities. Default: None.
- **hud_hidden** (bool) - Optional - Whether to hide the in-game HUD. Default: False.
- **render_distance** (int) - Optional - Number of chunks rendered around the player. Default: 6.
- **simulation_distance** (int) - Optional - Number of chunks simulated around the player. Default: 6.
- **eye_distance** (float) - Optional - Distance between the eyes (e.g., for binocular vision). Default: 0.0.
- **structure_paths** (List[str]) - Optional - Paths to pre-defined structures to be loaded. Default: None.
- **no_fov_effect** (bool) - Optional - Disables FOV changes due to movement effects. Default: False.
- **request_raycast** (bool) - Optional - Whether to request raycasting data. Default: False.
- **screen_encoding_mode** (ScreenEncodingMode) - Optional - Encoding mode for screen output. Default: ScreenEncodingMode.RAW.
- **requires_surrounding_blocks** (bool) - Optional - Whether to include surrounding block information. Default: False.
- **level_display_name_to_play** (str) - Optional - Name of the level to load. Default: "".
- **fov** (int) - Optional - Field of view setting. Default: 70.
- **requires_biome_info** (bool) - Optional - Whether to include biome information in observations. Default: False.
- **requires_heightmap** (bool) - Optional - Whether to include the world's heightmap. Default: False.
- **requires_depth** (bool) - Optional - Whether to include depth information. Default: False.
- **requires_depth_conversion** (bool) - Optional - If True, depth values are transformed into real-world distances and normalized. The conversion uses a near plane of 0.05 and a far plane set to 4.0 * view distance. Default: True.
- **resource_zip_path** (str) - Optional - Path to a resource pack zip file. Default: "".
- **block_collision_keys** (List[str]) - Optional - Keys for block collision detection. Default: None.
- **entity_collision_keys** (List[str]) - Optional - Keys for entity collision detection. Default: None.

### Enums
#### GameMode
- **SURVIVAL** - Standard gameplay with survival mechanics.
- **HARDCORE** - Like survival, but with perma-death enabled.
- **CREATIVE** - Free building mode with unlimited resources.

#### Difficulty
- **PEACEFUL** - No hostile mobs, health regenerates automatically.
- **EASY** - Hostile mobs spawn but deal reduced damage.
- **NORMAL** - Standard difficulty.
- **HARD** - More difficult survival experience with stronger mobs.

#### WorldType
- **DEFAULT** - Standard Minecraft terrain.
- **SUPERFLAT** - A completely flat world.
- **LARGE_BIOMES** - Biomes are larger than normal.
- **AMPLIFIED** - Extremely tall and chaotic terrain.
- **SINGLE_BIOME** - Entire world consists of one biome.

#### DaylightMode
- **DEFAULT** - Normal day/night cycle.
- **ALWAYS_DAY** - Locked to daytime.
- **ALWAYS_NIGHT** - Locked to nighttime.
- **FREEZED** - Time is frozen at a specific moment.
```

--------------------------------

### Generate proto files manually with protoc

Source: https://yhs0602.github.io/CraftGround/develop

Run the protoc compiler to generate Python, Java, and Kotlin code from proto definitions.

```bash
cd src/
protoc proto/action_space.proto --python_out=craftground
protoc proto/initial_environment.proto --python_out=craftground
protoc proto/observation_space.proto --python_out=craftground
protoc proto/action_space.proto --java_out=craftground/MinecraftEnv/src/main/java/ --kotlin_out=craftground/MinecraftEnv/src/main/java/
protoc proto/initial_environment.proto --java_out=craftground/MinecraftEnv/src/main/java/ --kotlin_out=craftground/MinecraftEnv/src/main/java/
protoc proto/observation_space.proto --java_out=craftground/MinecraftEnv/src/main/java/ --kotlin_out=craftground/MinecraftEnv/src/main/java/
```

--------------------------------

### Configure GPU for VirtualGL

Source: https://yhs0602.github.io/CraftGround/installation/headless.html

Configure the X server for the GPU using the identified BusID.

```bash
sudo nvidia-xconfig -a --allow-empty-initial-configuration --use-display-device=None --virtual=1920x1200 --busid PCI:104:0:0
```

--------------------------------

### Fast Lidar Configuration for RL Training

Source: https://yhs0602.github.io/CraftGround/lidar_feature.html

Recommended configuration for real-time RL training with minimal ray count.

```python
LidarConfig(horizontal_rays=16, max_distance=50.0, vertical_rays=1)
```

--------------------------------

### View Project Directory Structure

Source: https://yhs0602.github.io/CraftGround/blog/technical_report.html

Displays the project hierarchy excluding build artifacts and temporary files using the tree command.

```bash
 tree -d -I venv -I build -I __pycache__ 
.
├── craftground
│   ├── MinecraftEnv (Git submodule: https://github.com/yhs0602/MinecraftEnv)
│   │   ├── gradle
│   │   │   └── wrapper
│   │   └── src
│   │       └── main
│   │           ├── cpp
│   │           ├── java
│   │           │   └── com
│   │           │       └── kyhsgeekcode
│   │           │           └── minecraft_env
│   │           │               ├── client
│   │           │               ├── mixin
│   │           │               └── proto
│   │           ├── proto
│   │           └── resources
│   ├── craftground
│   │   ├── proto
│   │   └── proto_proto
│   ├── environments
│   └── wrappers
├── dejavu-fonts-ttf-2.37
│   ├── fontconfig
│   └── ttf
├── docs
├── figures
├── paper
└── poster
    └── _minted-poster
```

--------------------------------

### Run formatters using dev_tools.sh

Source: https://yhs0602.github.io/CraftGround/develop

Source the development tools script and execute the format_code function.

```bash
source ./dev_tools.sh
format_code
```

--------------------------------

### Set JDK 8 via jenv

Source: https://yhs0602.github.io/CraftGround/blog/install_minerl.html

Set the local JDK version to 1.8 using jenv.

```bash
jenv local 1.8
```

--------------------------------

### add_commands

Source: https://yhs0602.github.io/CraftGround/action_space.html

Executes Minecraft commands in a Gymnasium environment. Commands are issued at the next step() call.

```APIDOC
## add_commands

### Description
Executes a list of Minecraft commands in the environment. The commands are issued at the next step() call.

### Method
add_commands

### Parameters
- **commands** (list of string) - Required - List of Minecraft commands to execute.

### Request Example
```python
self.get_wrapper_attr("add_commands")(
    [
        "setblock 1 2 3 minecraft:cake"
    ]
)
```

### Response
No return value.
```

--------------------------------

### Find Minecraft Process

Source: https://yhs0602.github.io/CraftGround/troubleshooting.html

Use jps to list Java processes and identify the Minecraft instance, typically named DevLaunchInjector.Main.

```bash
jps -l
```
Tokens:
Raw