View project on GitHub

Building mods for Minecraft is complicated, and doing anything advanced can be very manual, since very little is done for you. LibrarianLib was created to fix this, providing a number of tools and frameworks to make advanced modding simpler and easier.


The extent of Minecraft’s GUI framework is giving you an OpenGL context, simple functions to draw primitives, input events, and very basic button/text controls. This is usable when creating very basic user interfaces, but anything advanced quickly becomes unwieldy, so often mods that contain complicated interfaces will each end up creating some kind of custom GUI library to handle this. Facade started out as just that, a set of in-house GUI utilities for my team’s mod, Wizardry. However, when we created LibrarianLib, those utilities were split off into it as a separate framework, and over the past four years has been continually improved as I’ve incorporated new lessons and experience into every new version. For a breakdown of Facade’s major features, see its dedicated page.


Because Minecraft is written in Java, memory performance can be a concern with large numbers of temporary objects. Minecraft’s default particles are each a complex object, that often will allocate dozens of temporary objects every tick. Minecraft’s particle collision detection simply reuses the entity collision detection code, which hasn’t been optimized for the large number of collision tests involved, meaning it doesn’t take many particles to make the game chug.

LibrarianLib’s particle systems on the other hand are inspired by a feature highlight I saw of Unreal Engine’s Niagara particle system. Instead of complex objects, the system stores particles as compact float arrays and pools those arrays for reuse when a particle dies, meaning creating a new particle often causes no new allocations. The system uses pipelining to efficiently process the particles, features a highly efficient zero-allocation collision raycaster, and features optional depth sorting so you don’t have to waste time on it when you don’t need to (e.g. with additive blending, order doesn’t matter). All of which combines to mean that thousands of particles with full world collision can be simulated without serious performance impacts.


One of the notoriously manual processes when modding is saving and loading data from the save file and for transmission in a packet. To help with this, LibrarianLib includes a reflection-based automatic serialization/deserialization system that can handle both generic types and polymorphism (either via class name or preferably custom ID). The serializer will also detect constructors it can use to create new objects on the fly when an immutable value is modified (as opposed to many other libraries that use Java’s Unsafe to skip constructors altogether). LibrarianLib’s current serialization is set to be superseded by the Prism project for Minecraft 1.14.