Freedom Lib

Smarter self-rescue for stuck mobs — plus a callable toolbox for modders who want their mobs to dig, tunnel, climb, or neutralize hazards on their own.

Freedom is a library mod for NeoForge 1.21.1. It adds nothing visible by itself: no items, no recipes, no commands, no creative-tab entries. The value shows up when another mod opts in — most prominently Zombie Village, Freedom's primary consumer.

If you're installing this because another mod requires it, you can stop reading. Drop the jar in mods/, that's all the setup.

What it does

When a host mod registers a mob with Freedom, the mob gets a fallback toolbox for the moments vanilla pathfinding can't solve:

• Head buried in gravel, sand, or a cave-in → dig out
• Trapped in lava → place a foothold and step up
• Stuck at the bottom of a 1-wide pit → climb out on a self-cleaning ladder
• Submerged in water → swim up
• Walled in by a 2-block step → step-assist over
• Blocked by a pool or flowing water → fill, plug, isolate a falling column, or bridge across it

Host mods can also directly drive deliberate actions — digging a shaft straight down, tunneling toward a target, plugging a flowing water source, draining a pool with gravel, lifting a mob to an elevated build target, or neutralizing a body of water/lava by classifying it and choosing FILL-with-gravel or PLUG-with-cobble automatically.

Everything respects host-defined protection rules — claim mods, structure registries, build envelopes. Freedom never modifies a block your host says is off-limits.

The one block it adds

freedom:climb_scaffold — a hidden, non-obtainable, ladder-climbable rescue block placed automatically by three of the rescue primitives. It looks identical to vanilla scaffolding but doesn't suffer scaffolding's "distance breaks the chain" failure, and mobs actually climb it. No item, no recipe, no creative tab. Each placed block carries a 15-second self-destruct fuse so columns never linger after a rescue.

If you run a mod that breaks blocks in mobs' way (custom AI, anti-grief sweeps), exempt freedom:climb_scaffold so it doesn't get torn down mid-climb.

What's under the hood

• 8 auto-fire rescue primitives — invoked by host mods via a single registry call when a mob is stuck
• 11 caller-direct primitives — for deliberate digging, tunneling, hazard cleanup, and elevation, each returning a Result enum so callers can drive their own state machine
• Per-mob trackers for placed blocks, with deterministic cleanup on death, chunk unload, or server restart
• 210 gametests + full JUnit suite green — the primitive contract is heavily tested against a live Minecraft world

Requires / compatible with

• Minecraft 1.21.1
• NeoForge 21.1.224 or newer
• Java 21
• No required mod dependencies

Modpack authors

Safe to include. Freedom is dormant until a host mod calls into it. No config files, no environment variables, no commands, no resource pack. Server-side primitive logic only.

Modder integration

RescueRegistry.tryAll(mob, EscapeContext.freeform(stuckTicks, protectionPredicate, "MyMobTag"));

That's the auto-fire path in one line. The standalone primitives (DigDownStep, DigForwardStep, LiquidHandlerPrimitive, etc.) are static methods on their own classes — import and call.

Full API documentation, telemetry contract, primitive table, and integration examples: Freedom Lib on the Risen wiki.

License

All Rights Reserved. Free to use for players and to include in modpacks. See LICENSE.md in the source repo for the full grants.