LibrarianLib Wiki

LibrarianLib is a suite of libraries designed to streamline the modding process for Minecraft, specifically tailored for the mods created by Team Wizardry. It acts as a foundational layer that handles the complex "boilerplate" code required for modern modding, allowing developers to focus on creative content rather than technical minutiae.

While the library is primarily written in Kotlin, it is meticulously engineered to be fully compatible and easy to use within Java environments. It manages several critical aspects of modding, including:

• Automated Registration: Simplifies the process of adding blocks, items, and entities to the game.
• Networking (Courier): A robust packet-handling system.
• UI Framework (Facade): A sophisticated system for creating complex Graphical User Interfaces (GUIs).
• Rendering (Glint/Form): Advanced shader and model rendering utilities.

Version Differences

LibrarianLib has evolved significantly between Minecraft versions 1.12.2 and 1.17.1:

LibrarianLib is divided into several specialized modules, each handling a specific subset of modding functionality. This modular approach allows for better organization and performance.

Courier (Networking)

Courier is the networking module of LibrarianLib. It abstracts the complex packet-handling system of Minecraft into a simple, type-safe API. It handles the serialization and deserialization of data automatically, ensuring that information sent between the server and the client is accurate and efficient.

Facade (UI Framework)

Facade is a high-level UI library. Unlike standard Minecraft GUI code, which can be verbose and difficult to manage, Facade uses a component-based system. This allows developers to build interfaces using reusable elements like buttons, sliders, and text fields with automatic layout management.

Foundation (Registration & Utilities)

Note: This module is specific to the 1.12.2 version. Foundation handles the "dirty work" of Forge registration. It tracks events and ensures that blocks, items, and other registry entries are handed to the game at the correct time without the developer needing to manually subscribe to every registry event.

Glint & Form (Rendering)

Glint provides a shader API that allows for custom visual effects, such as specialized item glints or glowing textures. Form is the model-loading module, which assists in handling complex 3D models and custom baked models.

LibrarianLib is built with a focus on clean API design. Because it is written in Kotlin, specific measures are taken to ensure Java developers do not encounter "funky" code structures.

Java-Kotlin Compatibility

To maintain a clean Java API, the library utilizes several Kotlin annotations to prevent common interoperability issues. Developers should look out for the following patterns which indicate a "Rough API" that may need reporting:

• Static Access: Use of @JvmStatic to avoid needing to call SomeClass.INSTANCE or SomeClass.Companion.
• Field Access: Use of @JvmField to ensure constants are accessible as standard public fields rather than getters.
• Naming: Use of @JvmName to prevent classes from appearing with a Kt suffix (e.g., MathUtilsKt).
• Functional Interfaces: Use of standard Java functional interfaces (like Consumer or Supplier) instead of Kotlin's Function1/2 types to ensure lambda compatibility in Java.

Documentation Examples

Code examples for LibrarianLib are typically found in the test packages of the source code. These serve as live demonstrations of how to implement the various modules:

• Courier Examples: Located in com.teamwizardry.librarianlib.courier.example.
• Facade Examples: Located in com.teamwizardry.librarianlib.facade.example.

One of the most powerful features of LibrarianLib (particularly in 1.12.2) is the automated registration system. This system removes the need for manual RegistryEvent handling.

How it Works

1. Object Creation: The developer creates a block or item instance.
2. Hand-off: The object is passed to LibrarianLib's registration manager.
3. Automatic Processing: LibrarianLib automatically handles:
   • Registry name assignment.
   • Creative Tab assignment.
   • Model registration and state mapping.
   • Ore Dictionary (Tags) registration.

This system ensures that all assets are loaded in the correct order, preventing common "missing texture" or "invalid registry" errors that occur during manual registration.

Courier simplifies the communication between the Client (the player's computer) and the Server.

Packet Registration

In Courier, packets are defined as simple data classes. Once a packet is registered, Courier handles the underlying byte-buffer management.

Example Workflow

When a player clicks a button in a GUI (Facade), a Courier packet is sent to the server. The server receives the packet, validates the data, and updates the player's inventory or world state, then sends a confirmation packet back to the client to update the visual UI.

Facade is designed to create "responsive" UIs in Minecraft. Unlike the vanilla system which relies on hardcoded pixel coordinates, Facade allows for dynamic positioning.

Key Components

• Constraints: Define how an element should be sized or positioned relative to its parent (e.g., "Center this button" or "Make this panel 50% of the screen width").
• Event Listeners: Easily attach logic to mouse clicks, scrolls, or key presses.
• Layers: Manage the rendering order of UI elements to ensure tooltips and overlays appear correctly.
• Themes: Allows for global styling of UI components, making it easy to maintain a consistent look across a mod's various menus.

LibrarianLib includes a minimal configuration file, typically used for debugging or performance tuning of the library's core systems.

Configuration files are located in the /config/ folder of the Minecraft directory, named librarianlib.cfg or librarianlib-common.toml.