bettershulkers/README.md

# Better Shulkers

A Fabric mod for Minecraft 1.21.11 that enhances shulker boxes with a top-down flat view, tooltip previews, item hints, labels and a fill bar.

Better Shulkers focuses specifically on shulker boxes and aims to stay lightweight and simple. If you're looking for a more feature-rich mod that covers other containers as well, check out [Peek](https://modrinth.com/mod/peek) by henkelmax, which served as the original inspiration for this project.

## Features

- **Flat top-down view** — shulker boxes are displayed from above in GUIs instead of the default angled 3D view, making their lid fully visible
- **Tooltip grid preview** — hover over a shulker box to see its contents laid out in a grid
- **Item hints on the lid** — displays the most relevant item directly on the lid, both in GUIs and in the world
- **Custom labels** — shows the shulker box's custom name on the lid
- **Fill bar** — a durability-style bar indicating how full the shulker box is

## Screenshots

### Tooltip grid preview

Hovering over a shulker box shows its contents in a grid. The preview can appear when the box has items or always, depending on configuration.

![Tooltip grid preview](docs/Tooltip.png)

![Tooltip grid preview (filled shulker)](docs/TooltipFull.png)

### In inventories and containers

Flat top-down lid view with item hints inside a chest. The fill bar and the optional shulker-like background behind hints can each be toggled in settings.

**With fill bar**

![Item hints in a chest](docs/InChestPreview.png)

![Item hints without background](docs/InChestPreviewNoBackground.png)

**Without fill bar** (inventory slot / container — hints only, with or without background)

![Item hints without fill bar](docs/InChestPreviewNoFillBar.png)

![Item hints without fill bar or background](docs/InChestPreviewNoFillBarNoBackground.png)

### Placed in the world

Item hints appear on placed shulker boxes; custom names appear on the lid when renaming the box with an anvil.

![Shulker lids in the world](docs/ShulkersLidsInWorld.png)

![Shulker lid with custom label](docs/ShulkersLidWithLabelInWorld.png)

### Configuration (Mod Menu)

Settings are grouped under **Better Shulkers** in Mod Menu when [Cloth Config](https://modrinth.com/mod/cloth-config) is installed.

![Mod Menu entry](docs/ModMenuEntry.png)

![Tooltip preview options](docs/ModMenuTooltipTab.png)

![Item hints and related options](docs/ModMenuItemHintsTab.png)

## Installation

1. Install [Fabric Loader](https://fabricmc.net/use/) for Minecraft 1.21.11
2. Drop `bettershulkers-x.x.x+1.21.11.jar` into your `mods/` folder
3. (Optional) Install [Cloth Config](https://modrinth.com/mod/cloth-config) and [Mod Menu](https://modrinth.com/mod/modmenu) to access the in-game settings screen

## Configuration

All options are accessible through Mod Menu (requires Cloth Config). Available settings:

| Option | Default | Description |
|---|---|---|
| Show Tooltip Preview | When Filled | When to show the grid preview (Always / When Filled / Never) |
| Show Item Hints in GUI | On | Item and label hints on the lid in inventory and other GUIs |
| Show Item Hints in World | On | Item and label hints on the lid of placed shulker boxes |
| Item Display Type | Single Type | Which item to display on the lid (None / Single Type / Bulk / First Item) |
| Show Labels | On | Show the custom name on the lid |
| Hide Hint Background in GUI | Off | Hide the shulker-like background of item hints |
| Item Hints Scale | 100% | Scale of the item hint icon (50–200%) |
| Show Fill Bar | On | Show a fill bar on shulker boxes |

## License

[LGPL-3.0](LICENSE)