Beet Minecraft Pack Development Kit

Plugins in the beet pipeline operate in two phases: an entry phase and an exit phase. This is because plugins are conceptually wrapped around each other like layers.

By using the yield statement, a plugin can pause its execution, allow all dependent plugins (those it require()d) to run, and then resume to perform cleanup or finalization tasks.

Execution Flow:

1. Plugin enters (code before yield).
2. Plugin yields (pauses).
3. Dependent plugins run to completion.
4. Plugin resumes (code after yield).

This is useful for aggregating data from multiple plugins before writing a final file (e.g., merging multiple language entries into one .json file).

def add_translations_plugin(ctx: Context):
    # [Entry Phase] Initialize shared state
    ctx.meta["translations"] = {}
    
    yield  # <--- Wait for all other plugins to call 'set_translation'

    # [Exit Phase] Finalize and write files
    for code, data in ctx.meta["translations"].items():
        ctx.assets["minecraft:lang"].merge(data)

For complex logic, instead of using arbitrary metadata, you can package functionality into a Service. Services are instantiated via ctx.inject() and live for the duration of the pipeline.

Pattern for creating a service:

1. Define a class that accepts ctx: Context in its __init__.
2. In __init__, use ctx.require() to register a plugin method that handles the service's finalization (using yield).
3. Use ctx.inject(YourServiceClass) within plugins to access the service's API.

This provides a strongly-typed, explicit way to share state and logic across plugins.

from beet import Context

class Internationalization:
    def __init__(self, ctx: Context):
        self.languages = {}
        # Register the cleanup plugin automatically
        ctx.require(self.add_translations)

    def add_translations(self, ctx: Context):
        yield
        # Finalize: merge all collected languages into assets
        ctx.assets["minecraft"].languages.merge(self.languages)

    def set(self, key: str, **kwargs: str):
        # API for other plugins to use
        for code, message in kwargs.items():
            self.languages[code][key] = message

# Usage in a plugin:
def my_plugin(ctx: Context):
    i18n = ctx.inject(Internationalization)
    i18n.set("hello", en_us="hello", fr_fr="bonjour")

The Lectern snapshot format represents Minecraft font data using a JSON structure containing multiple font definitions. Each definition includes:

• Unicode Pages: A list of character strings representing the glyphs on a specific unicode page.
• Bitmaps: Objects defining a bitmap font, including:
  • type: Set to "bitmap".
  • file: The resource path to the image (e.g., "minecraft:font/ascii.png").
  • ascent: The vertical offset for the font.
  • chars: A 2D array of characters representing the pixel data or glyph mapping.
• Legacy Unicode: A definition for legacy unicode support, specifying:
  • type: Set to "legacy_unicode".
  • sizes: The path to the binary file containing glyph sizes (e.g., "minecraft:font/glyph_sizes.bin").
  • template: A string template for locating unicode page images (e.g., "minecraft:font/unicode_page_%s.png").

{
  "type": "bitmap",
  "file": "minecraft:font/ascii.png",
  "ascent": 7,
  "chars": [
    "\u0000\u0000...",
    "\u0020\u0021..."
  ]
}

In beet, DataPack and ResourcePack objects are dict-like primitives that map directly to the filesystem structure. The hierarchy follows this pattern:

1. Pack: The top-level object (e.g., DataPack). It contains namespaces.
2. Namespace: A dict-like object within the pack (e.g., pack["demo"]). Namespaces are created automatically.
3. Namespace Container: A dict-like object within a namespace that groups files by type (e.g., namespace.functions).
4. File Instance: The leaf nodes representing actual files (e.g., Function, Texture).

You can access containers via attribute access (e.g., .functions) or type-based indexing (e.g., [Function]). Files can also be added directly to a namespace, and the namespace will automatically dispatch them to the correct container based on their type.

from beet import DataPack, Function

pack = DataPack()
# Accessing via namespace and type
demo_namespace = pack["demo"]
demo_functions = demo_namespace[Function]

# Adding a file (automatic dispatch to container)
demo_functions["foo"] = Function(["say hello"])

# Equivalent attribute access
demo_namespace.functions["foo"]

Directives can be adjusted using modifiers specified in parentheses immediately after the directive name.

Content Modification Modifiers

• append: Concatenates the fragment content to existing content (available for all text-based namespaced resource directives).
• prepend: Adds the fragment content before the existing content.
• merge: Uses the beet merging strategy to combine the fragment with the existing file (useful for JSON files like minecraft:load).
• base64: Decodes the content of the code fragment from base64.
• download: Used with block fragments to download remote files from a URL.
• strip_final_newline: Removes the final newline at the end of code block fragments.

Syntax

@<directive_name>(<modifier>) <arg1> <arg2> ...

@function(append) tutorial:greeting
say This is added afterwards.

@function(prepend) tutorial:greeting
say This is added before.

@function_tag(merge) minecraft:load
{
  "values": ["#tutorial:something_else"]
}

@function_tag(base64) tutorial:something_else
ewogICJ2YWx1ZXMiOiBbInR1dG9yaWFsOnN0cmlwcGVkIl0KfQ==

@function_tag(download) tutorial:from_github
https://raw.githubusercontent.com/mcbeet/beet/main/examples/load_basic/src/data/demo/functions/foo.mcfunction

@function(strip_final_newline) tutorial:stripped
say This function doesn't have a final newline.