mcfonts 0.9.1.1

A library for exporting, manipulating, and working with Minecraft fonts

mcfonts is a modern, intuitive, and Pythonic library for working with Minecraft: Java Edition fonts.

It is designed to be easy to modify and extend new providers, glyphs, font loaders, and more. mcfonts is ergonomic, fully typed, and documented.

from pathlib import Path
from mcfonts.font import PrioritySortOrder, MinecraftFont
from mcfonts.glyph.bitmap import BitmapGlyph
from mcfonts.provider.import_all import import_all
from mcfonts.serde.minecraft import load_font_from_path
from PIL.Image import Image, merge

# Required to load providers, which are dynamic modules
import_all()

font: MinecraftFont = load_font_from_path(Path("assets/minecraft/font/default.json"))
print(font)  # -> MinecraftFont(3 providers => 1,205 characters)
print(len(font))  # Number of providers
for provider in font.get_providers(PrioritySortOrder.DESCENDING):
    for character, glyph in provider.items():
        # Providers can be treated like dictionaries
        print(glyph.show())
        if character > 0xFF:
            del provider[character]
        elif isinstance(glyph, BitmapGlyph):
            image: Image = glyph.get_image()
            r, g, b, a = image.split()
            # ALl BitmapGlyph images are in RGBA
            r = r.point(lambda i: i * 1.5)
            g = g.point(lambda i: i * 0.4)
            b = b.point(lambda i: i * 0.3)
            provider[character] = BitmapGlyph(merge("RGBA", (r, g, b, a)))

⚠️ mcfonts is in beta. The API may change drastically at any time; read the changelog carefully.

---

Table of contents

• Installation
• Features
• Documentation
• Changelog
• License
• External links

---

Installation

mcfonts requires Python 3.12+ and is available via PyPI:

python -m pip install mcfonts

For generating documentation:

python -m pip install mcfonts[docs]

"externally-managed-environment"

This error occurs on some Linux distributions, such as Fedora 38 and Ubuntu 23.04. It can be solved by either:

1. Using a virtual environment (venv).
2. Using pipx.
3. Bypassing it.

Dependencies

• fontTools: for exporting to OpenType
• Pillow: for processing font textures
• tinyunicodeblock: for font coverage summaries

Optional dependencies under docs:

• sphinx: for generating documentation
• sphinx-autoapi: for generating code documentation
• sphinxext-opengraph: for meta tags
• sphinx-immaterial: for documentation theme

---

Features

• Supports bitmap, space, unihex, ttf, reference, legacy_unicode providers
• Loads and saves fonts
• Creates fonts from scratch
• Lean memory usage
• Extensible, modular, and open (heavily interface-based)
• Fully documented and tested
• Pythonic API

---

Loading

Currently, mcfonts only supports loading Minecraft: Java Edition fonts:

from pathlib import Path
from mcfonts.font import MinecraftFont
from mcfonts.provider.import_all import import_all
from mcfonts.serde.minecraft import load_font_from_path

import_all()
font: MinecraftFont = load_font_from_path(Path("assets/minecraft/font/default.json"))

Saving

mcfonts supports saving to any number of formats. Currently, 4 are implemented:

• OpenType
• YAFF
• Unihex
• Minecraft

For example, for OpenType:

from pathlib import Path
from fontTools.ttLib.ttFont import TTFont
from mcfonts.font import MinecraftFont
from mcfonts.serde.opentype import MetadataOptions
from mcfonts.serde.opentype import save_font as opentype_save_font

ttf: TTFont = opentype_save_font(
    MinecraftFont(),
    MetadataOptions(name="My cool font", include_credits=True, author="me", license="OFL")
)

Approximate performance:

	OpenType	Unihex	YAFF	Minecraft
1 chars	0.9 ms	0.033 ms	0.004 ms	0.28 ms
10 chars	1.0 ms	0.075 ms	0.06 ms	0.457 ms
100 chars	65.5 ms	1.42 ms	2.4 ms	2.8 ms
1000 chars	435.8 ms	14.5 ms	31. ms	34. ms
10000 chars	1330.0 ms	154. ms	260. ms	280. ms

Complexity tends to be linear with respect to the number of providers. Each provider has its own complexity. OpenType is the most expensive due to contour tracing.

---

Documentation

Documentation for mcfonts is available at https://mcfonts.readthedocs.io.

Building locally

You can build the documentation yourself:

git clone https://gitlab.com/whoatemybutter/mcfonts.git
cd mcfonts
python -m pip install .
cd mcfonts/docs
sphinx-build . _build

If you have make, you can also use the included Makefile as a shortcut: make html

The result index will be at _build/html/index.html.

---

Changelog

The changelog is at CHANGELOG.md.

---

License

mcfonts is licensed under a modified version of the MIT license known as MIT NO-AI.

In addition to the standard MIT terms, it also stipulates:

In addition, the following restrictions apply:

1. The Software and any modifications made to it may not be used for the purpose of training or improving machine learning algorithms, including but not limited to artificial intelligence, natural language processing, or data mining. This condition applies to any derivatives, modifications, or updates based on the Software code. Any usage of the Software in an AI-training dataset is considered a breach of this License.
2. The Software may not be included in any dataset used for training or improving machine learning algorithms, including but not limited to artificial intelligence, natural language processing, or data mining.

Fonts created with this tool are under no explicit license; you can license them in any way you want. This includes under a paid license.

External links

• Font - Minecraft Wiki
• OpenType specification
• FontForge

---

mcfonts is not affiliated, endorsed, created, supported, or an official product by Mojang Studios in any way.