`mcfonts`#

mcfonts is a versatile, fast, and extensible package for working with Minecraft fonts.

mcfonts works with any valid font JSON and can export every kind of texture and sizing.

For more information, see https://gitlab.com/whoatemybutter/mcfonts/.

Read the documentation online at https://mcfonts.rtfd.io.

Licensed under the MIT license, see https://choosealicense.com/licenses/mit/ for details.
Formatted with Black, see https://github.com/psf/black.
Checked with Pylint, see https://pylint.org/.

Submodules#

Package Contents#

Classes#

MinecraftFont

The MinecraftFont class.

Functions#

`from_java_ambiguous`(→ MinecraftFont)	For file paths where the file pointed to is of an unknown type; it could be a JSON, ZIP, or directory.
`from_java_font_contents`(→ MinecraftFont)	Load a Java Edition font JSON into a `mcfonts.MinecraftFont`.
`from_java_font_file`(→ MinecraftFont)	Load a Java Edition font JSON into a `mcfonts.MinecraftFont`.
`from_java_pack_folder`(→ MinecraftFont)	Load a Java Edition resource pack into a `mcfonts.MinecraftFont`.
`from_java_pack_zip`(→ MinecraftFont)	Load a Java Edition resource pack ZIP into a `mcfonts.MinecraftFont`.
`from_java_resource_template`(→ MinecraftFont)	Given the path to a texture and the contents of an individual font provider,

class mcfonts.MinecraftFont(provider_list: list[providers.utils.AnyProvider | providers.options.OptionsProvider], is_monochrome: bool = True)#

The MinecraftFont class.

Requires the providers of a provider file, and the associated resources mapping.

You should never instantiate this class directly. Use mcfonts.importing.

If you need to add, modify, or remove providers, do it through self.providers; it's a list of Provider classes, each containing relevant fields and methods.

Be sure to run mcfonts.MinecraftFont.validate() after making any changes; it won't be done automatically.

Warning

If more than one mcfonts.providers.OptionsProvider is present in provider_list, only the last one will be used.

Parameters:

provider_list -- A list of providers, all which are instances of mcfonts.providers.utils.AnyProvider.
is_monochrome -- Whether font resources are loaded in grayscale or not. Default is True.

providers: list[providers.utils.AnyProvider] = []#: A list of all the providers, not including OptionsProvider. Do not iterate over this! Use yield_providers() instead.

compact(chars_in_row: int = 0, cell_size: tuple[int, int] = (0, 0), square_cells: bool = True, output_file: str | None = None) → tuple[list[str], PIL.Image.Image, tuple[int, int]]#

Take all "bitmap" providers and export every character sheet into a single sheet.

Characters are scaled according to the largest effective bounding box in all providers.

Parameters:

chars_in_row -- How many characters to fit inside each row of the resulting sheet. If this is 0, this will be set to the length of the first string in the "charlist" list. If this is negative, this will be set so that the resulting sheet is square. By default, this is 0 (auto first string).
cell_size -- What size to make each glyph cell. If this is (0, 0), this will be set to the largest dimensions of every glyph in glyphs. If this is any other tuple of numbers, TODO actually finish this
square_cells -- If True, each glyph's width will equal its height. This is based on whichever number is largest. If False, each glyph's width will be unrelated to its height.
output_file -- Where to write the sheet to. If this is None, nothing will be written.

Returns:

A list of the new characters, and the new file as a PIL.Image.Image.

compare(other: Self)#

Given other, compare the two, using self as a baseline.

The information compared is:

Character count
Blocks covered
Providers included

Parameters:: other -- A second instance of mcfonts.MinecraftFont to compare to.

count_providers() → dict[str, int]#

Return a counted summary of the providers this font contains.

This is future-proof, and will work with any provider as long as it has a "type" key.

Returns:: A summary of font's providers.

count_providers_total() → int#

Count the number of providers in the font.

Returns:: Number of providers.

coverage_report() → coverage_reports.CoverageReport#

Build a report of what characters this font contains.

This includes information like how many characters are in the font, and what Unicode blocks are covered.

Returns:: A dictionary of {"chars": int, "blocks": {str: int}}.

export(font_name: str, filter_instance: filters.Filter | None = None, include_credits: bool = True) → fontTools.ttLib.TTFont#

Export the Minecraft font into an OpenType font with Type 2 Charstring outlines.

The font is crafted through a TTX file (font XML), and characters are added in tables and given self-descriptive name mappings: ("u0954", "u1fae4", "u2605").

For some fields, the font's name will be "Minecraft <font name>".

The font mustn't contain over 65,535 characters, or else any additional characters won't be added, and the font will be saved prematurely.

Parameters:

font_name -- The name of the resulting font, not what its filename is. This will be passed to: mcfonts.utils.sanitize_font_name().
filter_instance -- An optional instance of mcfonts.filters.Filter. If supplied, filter rules will be obeyed.
include_credits -- To include basic copyright information and credits in the font file.

get_covering_providers(unirange_notation: str) → list[providers.utils.AnyProvider]#

Given a codepoint range, return a list of providers that cover these characters.

Parameters:: unirange_notation -- A string representing the requested range of chars. See https://pypi.org/project/unirange/.
Returns:: A list of the providers that cover codeopints defined in unirange_notation.

get_glyphs_in_unirange(unirange_notation: str) → dict[str, glyphs.BitmapGlyph]#

Given a unirange_notation, return a dictionary of the requested chars to their glyphs.

Parameters:: unirange_notation -- A string representing the requested range of chars. See https://pypi.org/project/unirange/.
Returns:: A list of the requested glyphs that match unirange_notation.

print_info(table_chars: bool = True, summary_only: bool = False) → None#

Print basic information about the font.

Parameters:

table_chars -- Whether to print a 'chars' list as a square table, or as a simple string. This only applies to mcfonts.providers.BitmapProvider.
summary_only -- If True, will only print the number of characters and providers.

regenerate_charlists() → dict#

Iterate through each resource and analyse it.

For each resource, an entry will be made in a dictionary that contains the same height and ascent fields as the original, except the "chars" list will be updated to reflect the glyphs in the associated resource.

Warning

This only works if the first character in the original charlist is present, and if the order is incremental (U+0100, then U+0101, then U+0102, so on).

If this condition isn't true, this function will fail. There are no checks for this rule.

Returns:: A dictionary matching a normal font JSON, with each "chars" list updated.

reload_to_monochrome() → None#

Replace the resources used in the providers with a grayscale version.

If the resource is already grayscale, this will have no effect. This modifies the resource of this provider in place, and can't be undone.

save(indent: int | str | None = '\t') → None#

Recursively write all providers to their original file locations.

This is different from exporting. The file is indented by default.

Warning

Not to be confused with export().

Warning

Doesn't save resources.

Parameters:: indent -- The indentation level, refer to json.dump() for possible values.

validate() → None#: Run basic structure checks on the providers of the font JSON.

yield_characters() → collections.abc.Iterable[str]#

Yield all the characters this font covers and has a definition for.

Note

Any character in mcfonts.constants.PADDING_CHARS isn't counted.

Returns:: A yield of strings of individual characters.

yield_providers(unwind_reference_children: bool = True) → collections.abc.Iterable[providers.utils.AnyProvider | providers.reference.AnyProviderNotReference]#

Yield the providers in this font.

By default, this will unpack reference providers and yield its children instead. Reference providers will never yield the same referenced font twice if unwind_reference_children is True.

Parameters:: unwind_reference_children -- Whether to yield a reference provider's children instead of the reference provider plainly. Usually, this is a good idea. This also prevents the same font from being yielded twice.
Returns:: A yield of AnyProvider, or AnyProviderNotReference if not unwind_reference_children.

mcfonts.from_java_ambiguous(path: str, read_colors: bool = False, strict: bool = True) → MinecraftFont#

For file paths where the file pointed to is of an unknown type; it could be a JSON, ZIP, or directory.

This function automatically figures out which function to use, and returns a MinecraftFont.

Parameters:

path -- The path to either a file or a folder.
read_colors -- If True, glyph will be loaded in 'RGBA'. If False, loaded in 'LA'. RGBA images incur heavy time cost. Be careful.
strict --
If True:
- Bad providers will raise an error.
- Missing files will raise an error.
If False:
- Bad providers will be ignored.
- Missing files will be skipped.

Returns:

A mcfonts.MinecraftFont instance.

mcfonts.from_java_font_contents(file_contents: dict, file_path: str, read_colors: bool = False, strict: bool = True) → MinecraftFont#

Load a Java Edition font JSON into a mcfonts.MinecraftFont.

Requires a "providers" list, and missing files will raise an error.

Parameters:

file_contents -- The contents of the font JSON file, loaded as a dictionary. This dictionary should include the base "providers" key.
file_path -- The path to the font JSON. This is needed for loading resources.
read_colors -- If True, glyph will be loaded in RGBA (Red, Green, Blue, Alpha). If false, loaded in LA. RGBA images incur heavy time cost. Be careful.
strict --
If True:
- Bad providers will raise an error.
- Missing files will raise an error.
If False:
- Bad providers will be ignored.
- Missing files will be skipped.

Returns:

A mcfonts.MinecraftFont instance.

Raises:

FileNotFoundError -- If a referenced file isn't found and strict is True.

mcfonts.from_java_font_file(file_path: str, read_colors: bool = False, strict: bool = True) → MinecraftFont#

Load a Java Edition font JSON into a mcfonts.MinecraftFont.

Requires a "providers" list, and missing files will raise an error.

Parameters:

file_path -- The file path to the font JSON.
read_colors -- If True, glyph will be loaded in RGBA. If false, loaded in LA. RGBA images incur heavy time cost. Be careful.
strict --
If True:
- Bad providers will raise an error.
- Missing files will raise an error.
If False:
- Bad providers will be ignored.
- Missing files will be skipped.

Returns:

A mcfonts.MinecraftFont instance.

Raises:

FileNotFoundError -- If a referenced file is not found and strict is True.

mcfonts.from_java_pack_folder(folder_path: str, font_file_name: str = 'default.json', namespace: str = 'minecraft', read_colors: bool = False, strict: bool = True) → MinecraftFont#

Load a Java Edition resource pack into a mcfonts.MinecraftFont.

The font must be in the path assets/<namespace>/font/<fontfile>.

Parameters:

folder_path -- The path to the folder that contains a resource pack. This is not the assets folder, nor is it a ZIP file. The files inside this folder should be assets/, and pack.mcmeta.
font_file_name -- The name of the font file. By default, this is "default.json".
namespace -- The namespace to find assets in. By default, this is "minecraft".
read_colors -- If True, glyph will be loaded in 'RGBA'. If False, loaded in 'LA'. RGBA images incur heavy time cost. Be careful.
strict --
If True:
- Bad providers will raise an error.
- Missing files will raise an error.
If False:
- Bad providers will be ignored.
- Missing files will be skipped.

Returns:

A mcfonts.MinecraftFont instance.

Raises:

FileNotFoundError -- If a referenced file isn't found and strict is True.

mcfonts.from_java_pack_zip(file_path: str, password: bytes | None = None, read_colors: bool = False, strict: bool = True) → MinecraftFont#

Load a Java Edition resource pack ZIP into a mcfonts.MinecraftFont.

The font must be in the path assets/<namespace>/font/<fontfile>.

Parameters:

file_path -- The path to the ZIP file.
password -- Password to use when reading the ZIP file. Set to None if there is no password.
read_colors -- If True, glyph will be loaded in 'RGBA'. If False, loaded in 'LA'. RGBA images incur heavy time cost. Be careful.
strict --
If True:
- Bad providers will raise an error.
- Missing files will raise an error.
If False:
- Bad providers will be ignored.
- Missing files will be skipped.

Returns:

A mcfonts.MinecraftFont instance.

Raises:

FileNotFoundError -- If a referenced file isn't found and strict is True.

mcfonts.from_java_resource_template(file_path: str, template_provider: dict | None = None, read_colors: bool = False, strict: bool = True) → MinecraftFont#

Given the path to a texture and the contents of an individual font provider,

return a mcfonts.MinecraftFont instance with it, and the resource in file_path.

template_provider["file"] can be any value, it will be overwritten anyway, although it must exist.

Parameters:

file_path -- The path to the PNG resource that needs templating.
template_provider -- An individual provider dictionary. Not a list of providers. By default, this is mcfonts.utils.templates.PROVIDER_ASCII.
read_colors -- If True, glyph will be loaded in 'RGBA'. If False, loaded in 'LA'. RGBA images incur heavy time cost. Be careful.
strict -- If a provider has bad data, an exception will be raised and no provider list will be returned if this is True. If this is False, it will be ignored.

Returns:

A mcfonts.MinecraftFont instance.

mcfonts#

Submodules#

Package Contents#

Classes#

Functions#

`mcfonts`#