FancyMenu APNG Loop Fix

Overview

FancyMenu APNG Loop Fix is a small, client-side Forge mod for Minecraft 1.20.1 that unlocks advanced animated menu buttons in FancyMenu.

FancyMenu can use APNG (animated PNG) files as custom button backgrounds. That is powerful for title screens and GUIs — but out of the box, play-once animations cannot reliably replay on every hover. This mod fixes that limitation and adds logic so paired normal and hover animations stay in sync.

It was originally built for the Liminal Industries Rescripted modpack: Backrooms-style title menu buttons that look invisible at rest, tear open on hover, then slowly heal shut when you move away — without looping or getting stuck after the first hover.

Main features

• APNG replay fix — Patches FancyMenu so loop=1 (play once, then hold) animations can restart after they finish. Without this, the first hover works and later hovers stay frozen.

• Synchronized dual-texture playback — Keeps a button's normal and hover APNG backgrounds mirrored frame-for-frame during rip, regen, and idle states.

• Tear-on-hover, heal-on-unhover — Hover plays the rip animation once and holds open. Un-hover runs a slow regen on the normal texture. Re-hover resumes the tear from wherever the button had healed to.

• Idle breathing at rest — After fully healed, the mod loops only the breathing section of the normal APNG so buttons feel alive while staying mostly transparent.

• Client-only — Menus are rendered on the client. This mod is not required on dedicated servers and will not affect gameplay.

The problem this mod solves

In FancyMenu's APNG handler, when an animation finishes with loop=1, an internal flag is set and never cleared when the texture is reset. The playhead may rewind, but the animation engine refuses to tick forward again.

That leaves you with two bad options:

• Play once (loop=1) — no infinite looping, but cannot replay on re-hover.
• Infinite loop (loop=0) — can reset, but the tear keeps cycling while hovered.

This mod adds a third path: play once, replay every hover, never loop while held.

How to use this mod

For players

1. Install Minecraft 1.20.1, Forge 47+, and FancyMenu 3.6+.
2. Place fmloopfix-1.0.0.jar in your mods folder alongside FancyMenu.
3. Launch the game. If your pack or layout already uses compatible FancyMenu APNG buttons, the effect works automatically — no config file or keybind.

You do not need this mod on a server to join multiplayer. It only affects how your client draws FancyMenu widgets.

For FancyMenu / pack authors

This mod is designed for buttons that use two APNG backgrounds:

• Normal background — regen (heal) frames + optional idle breathing loop at the end.
• Hover background — rip/tear frames that play once and hold on the last frame.

Recommended FancyMenu layout settings per button:

• restartbackgroundanimations = false — the mod owns playback timing.
• Unique APNG file path per button — FancyMenu shares animation state by path; duplicate paths = broken sync.
• Export APNGs with loop=1 for both normal and hover textures.

Normal APNG structure (recommended):

1. Regen frames — peel/heal from open back to closed.
2. Breathing frames — subtle idle pulse after regen (mod loops this section when healed).

Hover APNG structure (recommended):

1. Start transparent or closed.
2. Rip frames — tear open once.
3. Hold on the final open frame.

Modpack integration

• Mark as a client dependency in your CurseForge modpack.
• Add a hard dependency on FancyMenu.
• Ship your FancyMenu layout + APNG assets; this jar is the runtime that makes the animation behavior work.

Requirements

Disclaimer

This is not an official FancyMenu addon. FancyMenu APNG Loop Fix is an independent compatibility patch created by Liminal Industries. It is not affiliated with, endorsed by, or maintained by Keksuccino (the FancyMenu author). FancyMenu remains a separate project.

Intended use: Built for the Liminal Industries Rescripted modpack's Backrooms-themed main menu — invisible-at-rest buttons, wallpaper-reveal tears, slow regen, and idle breathing on the title screen. Published so other packs and FancyMenu authors can reuse the same pattern without manually patching FancyMenu.

What this mod does not do:

• Does not add items, blocks, or gameplay mechanics.
• Does not change server gameplay or world generation.
• Does not replace FancyMenu — you still configure layouts and assets in FancyMenu.
• Does not guarantee behavior on every FancyMenu version (targets 3.6.x on 1.20.1 Forge).

Uses Mixins to adjust FancyMenu's APNG texture behavior at runtime. Use at your own discretion.

Credits

• Author: Liminal Industries
• License: MIT
• Built for: Liminal Industries Rescripted
• Patches behavior in: FancyMenu by Keksuccino