Quickstart

New Projects

For new projects, we recommend using our shaderpack template. It includes the bare necessities for a shaderpack, as well as some infrastructure to make it easy to run Block Wrangler.

Prerequisites

Our template uses a command-line utility called cookiecutter to provide additional flexibility when starting a new shaderpack using Block Wrangler.

To install it, run:

pipx install cookiecutter

Create a Repository

Create a new repository in your version control system of choice. Clone your repository to your local machine, but don't cd into it just yet!

In the enclosing folder, run this command to populate your new repository with the template:

cookiecutter gh:camplowell/shader_templates -f

tip

This template includes a .gitignore file to prevent committing virtual environments, cache files, and other things you probably don't want to commit.
However, you may need to modify it to get everything working perfectly for you.

Block Wrangler is ready to use! Don't forget to commit and push your changes to your repository.

Existing Projects

To add Block Wrangler to existing projects, you can install it from your package manager of choice, or from source:

Installation

virtual environment

python -m venv ./venv
source ./venv/bin/activate
pip install block-wrangler

Extra features

To get more detailed error messages when something goes wrong, add [fuzzy_tags] to your install command, like so:

pip install block-wrangler[fuzzy_tags]

user-wide

pip install --user block-wrangler

note

Installing libraries globally is generally not recommended.

Extra features

To get more detailed error messages when something goes wrong, add [fuzzy_tags] to your install command, like so:

pip install --user block-wrangler[fuzzy_tags]

from source

cd central/folder
git clone https://github.com/camplowell/block_wrangler.git
cd your/shaderpack
pip install -e central/folder/block_wrangler

note

Installing from source will not generate a portable requirements.txt file, so be aware before publishing your shaderpack on Github.
However, it will allow you to create custom versions of Block Wrangler for your own use, or to contribute to the project.

Extra features

To get more detailed error messages when something goes wrong, add [fuzzy_tags] to your install command, like so:

pip install -e 'central/folder/block_wrangler[fuzzy_tags]'

Repository maintenance

I recommend adding this .gitignore file to your repository.
You may need to modify it to get everything working perfectly for you, but it's a good starting point to make sure you don't accidentally commit your pycache or virtual environments to the repository.

Generate a requirements.txt file using:

pip freeze > requirements.txt

This file will be used by contributors to ensure they have the same dependencies as you.

Configuration

At the root of your shaderpack, create a block_properties.py file with the following contents:

block_properties.py

from block_wrangler import *
from pathlib import Path


shaderpack_root = Path(__file__).parent

def main():
	tags = load_tags()

	mapping = BlockMapping.solve({
		'sway': EnumFlag({
			'upper': tags['sway/upper'],
			'lower': tags['sway/lower'],
			'hanging': tags['sway/hanging'],
			'floating': tags['sway/floating'],
			'full': tags['sway/full']
		}),
		'sway_slow': Flag(tags['sway/slow']),
		'crops': tags['minecraft:crops'], # Vanilla tags are included
		'water': blocks('minecraft:water') # Individual blocks can also be referenced by name
	})

	with shaderpack_root.joinpath('shaders/block.properties').open('w') as f:
		f.write(mapping.render_encoder())
	with shaderpack_root.joinpath('shaders/util/block_properties.glsl').open('w') as f:
		f.write(mapping.render_decoder())

if __name__ == '__main__':
	main()

Usage

run python block_properties.py to generate the block properties and decoder GLSL files.