# Shimmer

Shimmer is a data pack inspired by the Shimmer liquid in Terraria. It enables players to uncraft items **whether in vanilla or modded gameplay**, only by dropping them into a source water block near the bottom of the Overworld. The same ZIP file also contains an optional resource pack for Minecraft 1.21.11 and later.

## Installation

### Data Pack

Place the Shimmer ZIP file in your world's `datapacks` folder. Do not extract it for a normal installation.

```text
.minecraft/saves/<world>/datapacks/<Shimmer ZIP file>
```

The included uncrafting data was generated for vanilla Minecraft 1.21 and later. No additional setup is required. If you have some recipes involving modded items, or you are playing with some custom recipes from other data packs, or a later Minecraft version adds or changes crafting recipes, regenerating the uncrafting data is only necessary when you want Shimmer to use those new or changed recipes.

### Resource Pack

The same ZIP file can also be used as a resource pack, but the resource-pack content supports only Minecraft 1.21.11 and later. Installing it as a resource pack does not install the data pack, so use a second copy of the ZIP if you want both parts enabled.

#### Global Installation

This method enables the resource pack from the Resource Packs menu and makes it available to every world.

1. Open **Options → Resource Packs → Open Pack Folder**.
2. Place the Shimmer ZIP file directly in the opened `resourcepacks` folder. Do not extract or rename it.
3. Return to Minecraft and move Shimmer into the selected resource packs list.

The resulting path is:

```text
.minecraft/resourcepacks/<Shimmer ZIP file>
```

#### Installation for One World

Use this method when distributing a map or when the resource pack should load automatically only for one world. Use a second copy of the ZIP and rename that copy to `resources.zip`.

For Minecraft 1.21.11 through 26.1 Snapshot 5, place `resources.zip` directly in the world folder, next to `level.dat` and the `datapacks` folder:

```text
.minecraft/saves/<world>/resources.zip
```

For Minecraft 26.1 Snapshot 6 and later, create a `resourcepacks` folder inside the world folder and place `resources.zip` there:

```text
.minecraft/saves/<world>/resourcepacks/resources.zip
```

Do not place the only copy of the pack in the world-resource-pack location. The ZIP must still also be present in the world's `datapacks` folder for Shimmer's data-pack functions to work.

## Updating Shimmer for Another Minecraft Version or Modded Items

Shimmer's uncrafting functions are generated from Minecraft's recipe and item-tag data. To use the pack with another version, first regenerate those functions from that version's game JAR.

1. Extract the Shimmer ZIP file.
2. Locate the target version's Minecraft game or mod `.jar` file and extract it.
3. Delete the existing contents of `config/recipe` and `config/item` in the extracted Shimmer folder.
4. Copy the contents of `data/minecraft/recipe` from the game JAR into `config/recipe`.
5. Copy the contents of `data/minecraft/tags/item` from the game JAR into `config/item`.
6. Apply the command changes for your target version described below.
7. From the root of the extracted Shimmer folder, run:

   ```bash
   python config/generate_uncraft.py
   ```

8. Compress the contents of the Shimmer folder into a new ZIP file. Make sure that `pack.mcmeta`, `data`, and `config` are directly inside the ZIP rather than inside an additional outer folder.

## Features

- **Shimmer** — Source water blocks between Y=-64 and Y=-54 in the Overworld act as Shimmer.
- **Uncrafting** — Drop a supported item into Shimmer to recover ingredients from its crafting recipe. The source water block is consumed when uncrafting succeeds.
- **Custom recipe support** — Replace the files in `config/recipe` and `config/item` with recipe and item-tag data from another data pack or mod, then run `config/generate_uncraft.py` to rebuild the uncrafting functions.
- **More Shimmer mechanics planned** — Future updates may add more mechanics found in *Terraria*'s Shimmer, including material transmutation, new items, and other related features.

## Limitations

- When a recipe accepts an item tag, Shimmer returns the first valid item listed by that tag because Minecraft does not preserve which tagged ingredient was originally used.
- Milk buckets and honey bottles are treated as non-returnable ingredients.
- Items with stored components are checked before component-free variants, but exact component equality cannot always be guaranteed by vanilla NBT matching.
- The generator processes shaped and shapeless crafting recipes only. Stonecutting and other recipe types are ignored.

## Reporting Bugs

Open the `Issues` tab and select `New issue`. Include:

- The Shimmer version
- The Minecraft version
- Any other installed data packs or mods
- Steps that consistently reproduce the problem
- Relevant screenshots, videos, logs, or command output

## License and Credits

Shimmer is free software licensed under the GNU General Public License version 3 only (`GPL-3.0-only`).

Copyright © 2026 ZhuinZ and Shimmer contributors.

Minecraft is a trademark of Microsoft Corporation. *Terraria* is a trademark of Re-Logic.

**NOT AN OFFICIAL MINECRAFT PRODUCT. NOT APPROVED BY OR ASSOCIATED WITH MOJANG OR MICROSOFT.**

## Release Notes

### v1.0.0
- Shimmer now can uncraft items.

### v1.0.1
- Shimmer now can only be in Overworld.

### v1.1.0
- Manual updates for vanilla Minecraft are no longer required.
- Improved visual effects when using resource pack.

### v1.1.1
- Fixed some bugs.

### v1.1.2
- Improved visual effects when using resource pack.