mciwb

Minecraft Interactive World Builder.

This project is intended as a fun way to learn the Python Programming Language.

Experienced Python programmers can also use this library to create Minecraft worlds with interactive Python features.

What	Where
Source	gilesknap/mciwb
Install	pip install git+https://github.com/gilesknap/mciwb.git
Container	podman run --rm -it --network host ghcr.io/gilesknap/mciwb:latest shell
Documentation	https://gilesknap.github.io/mciwb
Releases	gilesknap/mciwb

Quick Start

To get started learning Python, see Introduction

For existing Python developers, see API documentation

In short: start a local Minecraft server and build in it from a script:

mciwb start            # a Minecraft 26.3 server in podman, on localhost
mciwb run build.py     # run a build script, or `mciwb shell` for IPython

where build.py uses the world object and the names from mciwb.imports:

pos = Vec3(632, 73, -1658)
world.set_block(pos, Item.GOLD_BLOCK)
polygon(get_client(), pos + Direction.EAST * 10, height=5, diameter=7)

The commands use the RCON password default_pass unless you give one. Give it with --password-file FILE or the MCIWB_PASSWORD environment variable rather than --password, which other users can see with ps.

Example Build

The pagoda and castle with working portcullis were all created programmatically with Python and the current version of MCIWB.

https://github.com/gilesknap/mciwb/assets/964827/026b3551-f514-403a-bebe-8d168c7170b0

An earlier video shows the castle being built; the source code for the village is in src/mciwb/demo/village.py.

https://user-images.githubusercontent.com/964827/225131152-677da86e-a6b5-44c2-baf1-8da2eb4e221b.mov

Goals

Minecraft Interactive World Builder’s goals are:

• Use Python to create anything inside of Minecraft worlds.

• Call Python code when events occur inside the world.

• Use an iPython prompt to interact with the world by typing Python commands

• Have your player inside the world execute Python code by placing command signs or activating switches/levers with Python actions.

All instructions on how to set up a Minecraft Server and the Python developer environment are included. There are step by step tutorials to introduce Python Programming and the features of Minecraft Interactive World Builder.

Note: this is a work in progress. There are now enough tutorials to learn the fundamentals of Python and enough functionality to have some fun interacting with Minecraft from Python code.

Credits

This project would not be possible without mcipc, which provides the client library for Minecraft RCON.

How the documentation is structured

Documentation is split into four categories, also accessible from links in the top bar.

• Tutorials
  • Introduction
  • Installation
  • Orientation
  • Python Variables
  • Loops
  • Functions
  • Modules and Packages
  • If - Else
  • Lists
  • Classes
  • Dictionaries
  • Running Code in the Background
  • Levers and Switches
  • Action Signs
  • Moving Structures
  • Installation

Tutorials for installation and typical usage. New users start here.

• How-to Guides
  • Backup and Restore
  • Build with Roofs, Arches, Stairways and Schematics
  • Build with Claude Code
  • Command Completion
  • Contribute to the project
  • Discovering the Coordinates of a Block
  • VSCode Extensions
  • Render a Build to an Image
  • Run in a container
  • Setup for each Tutorial
  • Troubleshooting
  • Windows Subsystem for Linux

Practical step-by-step guides for the more experienced user.

• Explanations
  • Minecraft’s Coordinate System
  • Architectural Decision Records
  • About the documentation
  • Comparison with Minecraft Education Edition
  • MCIPC Client object
  • Variable Scope
  • Minecraft Server Config

Explanations of how it works and why it works that way.

• Reference
  • API
  • Demo Code
  • Index
  • Release Notes

Technical reference material including APIs and release notes.