Moonlight Lib is a library mod that provides dynamic data pack and resource pack utilities, custom map markers, villager AI helpers, and block set registration for Minecraft Fabric, Forge, and NeoForge. Created by MehVahdJukaar, it serves as a shared foundation that other mods depend on to access advanced features not available in vanilla Minecraft's modding API.
Minecraft modding has a recurring problem: dozens of mods need the same complex features — dynamic wood types, custom map icons, modified villager behavior — but each mod reimplementing those systems leads to conflicts and bloated installs. Moonlight Lib solves this by providing a single, well-maintained library that any mod can hook into. With over 26 million downloads on Modrinth alone, it has become one of the most widely depended-upon library mods in the ecosystem. If you have ever installed Supplementaries or Every Compat, you have already been using Moonlight Lib behind the scenes. Understanding what it actually does helps you appreciate why so many popular mods require it and why keeping it updated matters for a stable modpack.
Key Features of Moonlight Lib
- Dynamic Resource Pack Utilities — Moonlight Lib can generate resource packs and data packs at runtime, meaning mods that depend on it can resprite textures and register new assets without shipping massive static files. This is especially useful for mods that add wood-based blocks, since the library can automatically retexture planks, stairs, slabs, and fences to match any custom wood type. For players, this translates to smaller mod downloads and fewer texture conflicts between mods.
- Dynamic Block Set Registration — One of the trickiest problems in Minecraft modding is registering blocks that depend on other blocks that haven't been registered yet. Moonlight Lib handles this timing issue by scanning all registered blocks, building a complete block set, and then allowing dependent blocks to register at precisely the right moment. In practice, this is what gives you seamless dynamic wood type support — mods can add new wood variants that automatically get matching stairs, doors, fences, and more without manual configuration.
- Custom Map Markers — The library includes a complete system for adding custom map decorations and markers with full control over rendering and tooltip data. Modders can even register new markers through data packs alone, making this system data-driven and extensible. For players, this means mods can place custom icons on your in-game maps — marking points of interest, structures, or mod-added locations — without conflicting with vanilla map behavior.
- Dynamic Villager AI — Modifying villager behavior in Minecraft is notoriously fragile because most approaches override the entire AI schedule, breaking other mods in the process. Moonlight Lib provides a helper system that lets mods add tasks and modify villager schedules dynamically and compatibly, without wiping out existing behavior. This is critical for modpacks where multiple mods want to tweak villager routines without stepping on each other.
- Custom First and Third Person Animations — The library offers simple interfaces that modders can implement directly in their item classes to add custom use animations similar to crossbows or the spyglass. This covers both first-person and third-person views plus a callback for custom item rendering. Players benefit from smoother, more polished animations on modded items rather than the stiff default hold pose.
- Soft Fluid System — Moonlight Lib introduces a data-driven virtual fluid system designed to fit vanilla Minecraft's style better than traditional fluid APIs. It supports multiple container types — bottles, bowls, and buckets — and works with consumable liquids like stews and drinks. The base unit is one Minecraft bottle rather than the more abstract forge millibucket, making it more intuitive for both modders and players interacting with fluid tanks.
- Dispenser Utilities & Grindstone Triggers — Smaller but valuable additions include code that lets modders register new dispenser behaviors without overriding existing ones, plus a custom advancement trigger for the grindstone. These quality-of-life APIs save modders significant development time and reduce the chance of inter-mod conflicts when multiple mods modify the same vanilla systems.
Screenshots
How to Install Moonlight Lib
- Choose and install the mod loader that matches your Minecraft version. For 1.21.1 and 1.21, use Fabric or NeoForge. For 1.20.1, Forge is also supported.
- Download the correct Moonlight Lib file for your Minecraft version and loader from the official download links below.
- Open your Minecraft installation folder and navigate to the
modsfolder. If it does not exist, launch the game once with your mod loader to generate it. - Place the downloaded Moonlight Lib
.jarfile into themodsfolder alongside any mods that require it. - Launch Minecraft through your mod loader profile and verify Moonlight Lib appears in the mod list.
Requirements & Compatibility
| Minecraft Version | Supported Loaders | Status |
|---|---|---|
| 1.21.1 | Fabric, NeoForge | Latest |
| 1.21 | Fabric, NeoForge | Supported |
| 1.20.1 | Fabric, Forge, NeoForge | Supported |
What's New
- Added new utilities for working with shapes and angles, expanding the library's geometry tools for dependent mods.
- Minor bug fixes improving overall stability.
- The library continues to receive regular updates — last updated March 27, 2026.
Pros and Cons
Pros
- Eliminates code duplication across dozens of dependent mods
- Supports all three major mod loaders — Fabric, Forge, and NeoForge
- Actively maintained since 2022 with frequent updates
- Data-driven systems (map markers, soft fluids) reduce the need for hard-coded patches
- Over 26 million downloads demonstrate strong community trust and reliability
Cons
- Provides no standalone gameplay — only useful when required by another mod
- Dynamic registration can occasionally cause load order issues in very large modpacks
- Updates to Moonlight Lib may temporarily break dependent mods until they catch up
Alternatives to Moonlight Lib
- Architectury API — A cross-platform modding abstraction layer that helps developers write mods for Fabric and Forge simultaneously, serving a similar role as a shared dependency.
- GeckoLib — A popular animation library focused on entity and item animations, complementing Moonlight Lib's animation features with more advanced keyframe-based systems.
- Cloth Config API — A widely used configuration screen library that, like Moonlight Lib, operates behind the scenes as a dependency for many popular mods.
Download Moonlight Lib
| Minecraft Version | Fabric | Forge | NeoForge |
|---|---|---|---|
| For Minecraft 1.21.1 | Download | — | Download |
| For Minecraft 1.21 | Download | — | Download |
| For Minecraft 1.20.1 | Download | Download | Download |
Always download mods from official sources to stay safe.
Frequently Asked Questions
Do I need Moonlight Lib if no other mod requires it?
No — Moonlight Lib is a library mod with no standalone gameplay features. You only need to install it when another mod explicitly lists it as a dependency. Mods like Supplementaries and Every Compat are among the most common mods that require it.
Is Moonlight Lib compatible with OptiFine or Sodium?
Yes, Moonlight Lib generally works alongside both OptiFine and Sodium without issues. Since it operates at the modding API level rather than modifying rendering pipelines, it does not conflict with performance optimization mods. However, always test your specific modpack combination to confirm stability.
Does Moonlight Lib affect game performance?
The impact appears to be lightweight for most setups. Moonlight Lib runs shared utilities that dependent mods would otherwise implement individually, so consolidating them into one library can actually reduce overhead compared to each mod shipping its own version of the same code.
Can I use Moonlight Lib on a multiplayer server?
Yes — Moonlight Lib works on both client and server sides. It must be installed on the server if any server-side mod depends on it, and all players connecting with dependent client-side mods will also need it installed locally.
Which Minecraft versions does Moonlight Lib support?
It currently supports Minecraft 1.21.1, 1.21, and 1.20.1. Fabric and NeoForge are available for all three versions, while Forge support is available specifically for 1.20.1. The mod has been actively updated since its initial release in June 2022.
