MasuGUI

MasuGUI

Premium data-driven server-side GUI library for Forge 1.18.2 with optional client-side enhanced rendering.

⚠ Personal-Use Release
This mod is published primarily for my own projects. No support is provided. No issue tracker, no feature requests, no help with integration. Use entirely at your own risk.

---

What It Does

MasuGUI lets other mods build rich, custom GUIs that render beautifully on clients with the mod installed, and transparently fall back to vanilla chest-based menus for players without it. Single JAR. One API. Two visual experiences from the same definition.

Routing logic:

• Client has MasuGUI → opens a custom rendered screen (gradients, animations, scrolling, etc.)
• Client does not have MasuGUI → opens a vanilla container (chest, hopper, anvil, merchant, etc.) with the same interactive elements

---

Highlights

• 14 element types - Panel, Label, Button, TextField, ItemGrid, ItemDisplay, Divider, ProgressBar, Image, ScrollPanel, Checkbox, Slider, TabBar, Dropdown, PlayerHead
• JSON-driven layouts - define GUIs in config/<modId>/gui/<name>/Enhanced.json and Fallback.json
• Hot-reload - /masugui reload [modId] reloads templates without a restart
• Animations - 6 easing functions, 8 animated properties, 3 play modes, all definable in JSON
• Remote textures - any texture field accepts a URL; downloaded async and cached to disk
• 18 vanilla fallback container types - chest sizes, hopper, dispenser, anvil, smithing, furnace, brewing, merchant, beacon, etc.
• Container slot redirects - real interactive inventory slots in fallback mode with drag-and-drop
• Cursor item system - pick-up/place item interaction in enhanced mode
• GUI Effects API - server-triggered cell animations (PULSE, FLASH, BOUNCE, FADE_OUT, SCALE_UP), client-side sounds, fullscreen reward reveals
• Quark protection - mixin blocks unwanted inventory transfers
• Auto-close - configurable distance, dimension change, and death detection
• Click sounds, tooltip delays, smooth hover transitions, two-pass z-ordered rendering

---

Element Reference

Element	Purpose	Interactive
Panel	Background rect with gradient, nine-slice, border	No
Label	Text with wrapping, centering, scaling, shadow	No
Button	Clickable with gradient, hover lerp, click sound	Yes
TextField	Real text input via EditBox	Yes
ItemGrid	Item grid with client-side scrolling, scrollbar	Yes
ItemDisplay	Single item with tooltip override	Yes
Divider	Horizontal/vertical separator	No
ProgressBar	Fill bar with gradient, label, smooth lerp	No
Image	Texture rendering with UV support (local or URL)	No
ScrollPanel	Scrollable container with scissor clipping	Yes
Checkbox	Toggle with label	Yes
Slider	Draggable value selector with range	Yes
TabBar	Tab switcher with active state	Yes
Dropdown	Expandable option list	Yes
PlayerHead	Player skull from skin texture (supports skinUrl)	No

---

For Mod Developers

MasuGUI is a library mod. It has no in-game content on its own. It provides an API for other mods to define GUIs once and have them render either as a custom screen or as a vanilla chest menu depending on the client.

Two ways to define a GUI:

1. Java builder API - MasuGui.builder("my_gui").size(300, 200).add(...).open(player);
2. JSON templates - layout files in the config folder with variables, data providers, and named action handlers

Run /masugui test in-game with the mod installed to explore six demo GUIs covering shops, settings, profiles, scrolling, merchants, and confirmations.

---

Commands

• /masugui test - open demo hub
• /masugui fallback - toggle force-fallback mode to preview chest rendering
• /masugui reload [modId] - hot-reload JSON GUI templates (OP level 2)
• /masugui editor <modId> <guiName> - in-game visual GUI editor (OP level 2)
• /masugui status - show client mod detection + fallback flag

---

Requirements

• Minecraft 1.18.2
• Forge 40.3.11 or newer
• Java 17

Optional: Quark (compile-time only, for the inventory transfer protection mixin)

---

Installation

1. Install Forge 1.18.2
2. Drop the JAR into your mods/ folder
3. Install on both server and clients. Clients without it will still work, but will see chest-based fallback GUIs instead of the enhanced renderer

---

License

All Rights Reserved. You may use this mod in modpacks and on servers. You may not redistribute, decompile, or rehost this JAR without permission.

---

Reminder: this is a personal-use release. No support, no issue tracker, no PRs accepted. If it works for you, great. If it does not, you are on your own.