English | 中文

Minecraftify2.0

A tool for converting 3D models to Minecraft, which needs to be used in conjunction with the Builder mod.

Project Introduction

This project is a tool for voxelizing 3D models and converting them into blocks in the Minecraft world (JAVA Edition).

It supports multiple 3D model formats, such as OBJ, STL, GLB, etc., and can perform conversions based on the materials (wool, concrete, terracotta, glass) selected by the user.

The generated data is saved in a JSON file and can be imported into Minecraft using the Fabric mod Builder. See the following sections for specific usage instructions.

This project is upgraded from Minecraftify1.0. The main changes compared to the previous version are:

• The old-version dependency libraries in the original project cannot adapt to the new game versions of Minecraft, and it is difficult to update and adapt them. To reduce maintenance costs, the new project no longer uses these dependency libraries to interact with MC.
• The new project uses the self-developed Fabric mod Builder to work with this project, adapting to the latest game version (1.21.8).

Installation

For Users

1. Download the latest release from the releases page
2. Extract the downloaded compressed package
3. Run Minecraftify2.exe to start the application

For Developers

1. Clone this repository
2. Install the required dependencies:

   pip install -r requirements.txt

3. Run gui.py to start the application, or use the command line tool python mcify.py to perform conversions:

   # simple usage
   python mcify.py model.obj
   # use more parameters
   python mcify.py model.obj --game_path "your_game_directory" --rotate 45,0,0 --pitch 0.5 --no-wool --no-glass
   # view detailed parameter descriptions
   python mcify.py --help 

4. If you need to compile it into an executable file, please use PyInstaller:

   pyinstaller -w -i ./image/logo.ico -n Minecraftify2 --exclude-module torch ./gui.py

Usage Instructions for GUI

1. Prepare the 3D model file you want to convert. Supported formats include OBJ, STL, PLY, GLB, etc.
2. Run Minecraftify2.exe or gui.py to start the tool interface.
3. In the interface, select the 3D model file you want to convert and the main directory of the Minecraft game (usually C:\Users\your_username\.minecraft).
4. Check the materials to be used for the conversion. Currently, wool, concrete, terracotta, and glass are supported.
5. You can expand the advanced options to set the rotation angle, voxel size, etc.
6. Click the "Convert" button to start the conversion.
7. After the conversion is completed, a JSON file will be generated, which contains the converted block data. (If you have selected the correct game directory before, the file will be automatically saved to the path required by the subsequent mod; otherwise, you need to manually copy the file to the correct path according to the requirements of the mod.)
8. Use the Fabric mod Builder to import the JSON file data into the Minecraft world. For the installation and usage methods of the mod, please refer to its repository description.

Notes

• The Rotation Angle is in degrees. Three angles are used to represent the rotation of the model in the x, y, and z axes.
• Setting a smaller voxel size can improve the conversion accuracy, but it will also increase the conversion time.
• The conversion process may take some time, depending on the complexity of the model.
• The color of the block will be selected automatically from the materials checked.
• The Builder mod is compatible with JAVA Edition 1.21.8.

File Description

• gui.py: The graphical user interface of the tool.
• tran.py: The core code for implementing the 3D model conversion logic.
• mcify.py: The command line tool for model conversion.

Future Plans

• Add more materials for conversion, and support for replacing existing blocks.
• Optimize the conversion process to reduce the conversion time.