Update README and add demo

Author: TheETR

README.md

@@ -1,25 +1,55 @@
 # ConfigStackMC
 
 <p align="center">
-  <img src="https://img.shields.io/github/v/release/TheETR/ConfigStackMC?style=for-the-badge&logo=github&label=Latest%20Release" alt="Latest GitHub release">
-  <img src="https://img.shields.io/github/downloads/TheETR/ConfigStackMC/total?style=for-the-badge&logo=github&label=Downloads" alt="GitHub release downloads">
-  <img src="https://img.shields.io/github/actions/workflow/status/TheETR/ConfigStackMC/release.yml?branch=main&style=for-the-badge&logo=githubactions&label=Release%20Build" alt="Release workflow status">
+  <a href="https://github.com/TheETR/ConfigStackMC/releases/latest">
+    <img src="https://img.shields.io/github/v/release/TheETR/ConfigStackMC?style=for-the-badge&logo=github&label=Latest%20Release" alt="Latest GitHub release">
+  </a>
+  <a href="https://github.com/TheETR/ConfigStackMC/releases">
+    <img src="https://img.shields.io/github/downloads/TheETR/ConfigStackMC/total?style=for-the-badge&logo=github&label=Downloads" alt="GitHub release downloads">
+  </a>
+  <a href="https://github.com/TheETR/ConfigStackMC/actions/workflows/release.yml">
+    <img src="https://img.shields.io/github/actions/workflow/status/TheETR/ConfigStackMC/release.yml?branch=main&style=for-the-badge&logo=githubactions&label=Release%20Build" alt="Release workflow status">
+  </a>
+</p>
 
+<p align="center">
   <img src="https://img.shields.io/badge/Paper-server%20plugin-2E7DDE?style=for-the-badge" alt="Paper server plugin">
   <img src="https://img.shields.io/badge/Fabric-singleplayer%20%2B%20server%20mod-DB8A00?style=for-the-badge" alt="Fabric singleplayer and server mod">
-  
   <img src="https://img.shields.io/badge/Java-25-B07219?style=for-the-badge&logo=openjdk&logoColor=white" alt="Java 25">
 </p>
 
-ConfigStackMC is a small Minecraft Java project that lets you change the stack size of specific items from a config file.
+<p align="center">
+  <strong>Change Minecraft item stack sizes with a simple config file.</strong>
+</p>
+
+---
+
+ConfigStackMC lets you change stack sizes for vanilla items and Fabric mod items from one simple config file.
+
+It works on Paper servers, Fabric singleplayer worlds, and Fabric multiplayer servers. Items you leave out of the config keep their normal stack size.
+
+By default, the included config uses vanilla values, so installing ConfigStackMC does **not** change gameplay until you edit it.
+
+<p align="center">
+  <a href="#-demo">Demo</a> •
+  <a href="#-download">Download</a> •
+  <a href="#-which-file-should-i-use">Which file?</a> •
+  <a href="#-configuration">Configuration</a> •
+  <a href="#-commands">Commands</a> •
+  <a href="#-troubleshooting">Troubleshooting</a>
+</p>
+
+---
 
-Want ender pearls to stack to 64? Totems to stack to 16? Buckets to stack to 16? Add the item id to the config, set the number, reload, and you are done.
+## 🎬 Demo
 
-By default, ConfigStackMC uses vanilla values, so installing it does **not** change gameplay until you edit the config.
+<p align="center">
+  <img src="assets/ConfigStackMC-demo.gif" alt="ConfigStackMC item stack size demo">
+</p>
 
 ---
 
-## Download
+## 📦 Download
 
 Download the latest build from the **Releases** page:
 
@@ -33,11 +63,11 @@ Each release contains separate files:
 | `ConfigStackMC-...-fabric.jar` | Fabric singleplayer or Fabric multiplayer servers | `mods/` |
 | `SHA256SUMS.txt` | Optional checksum verification | Nowhere; only for checking downloads |
 
-Do **not** download the source code zip unless you are a developer. Normal users only need one of the jar files above.
+> You only need the jar that matches your setup. The source code archives are there for developers who want to build the project themselves.
 
 ---
 
-## Which file should I use?
+## 🧩 Which file should I use?
 
 ### I run a Paper server
 
@@ -59,29 +89,23 @@ ConfigStackMC is designed to work on the logical server side. If your server set
 
 ---
 
-## Compatibility
+## ✅ Compatibility
 
-Releases are built for a specific Minecraft version. Always check the release title and release notes before downloading.
+Each release targets a specific Minecraft version. Check the release title before downloading and use the jar that matches your game or server version.
 
 Example release title:
 
 ```text
 ConfigStackMC v1.0.0-mc26.1.2
 ```
 
-The release workflow can automatically find the latest Minecraft version that has:
-
-- a stable Paper build
-- a matching Fabric API artifact
-- a successful ConfigStackMC build
-
-This means new Minecraft targets can be released without manually editing hardcoded version numbers every time.
+Paper and Fabric builds are provided separately for the same target version.
 
-Build success means the jars compile against that Minecraft/Paper/Fabric target. For main servers, test the jar on a small test world first.
+A successful build means the project compiled for that target. For an important server or world, test the new jar once before replacing your current setup.
 
 ---
 
-## Paper installation
+## 🛠️ Paper installation
 
 1. Download the `ConfigStackMC-...-paper.jar` file from Releases.
 2. Put it into your Paper server's `plugins/` folder.
@@ -99,57 +123,49 @@ plugins/ConfigStackMC/config.yml
 /stackconfig reload
 ```
 
-That is it. Vanilla clients can join normally.
-
 ---
 
-## Fabric installation: singleplayer
+## 🧵 Fabric installation
+
+Install Fabric Loader and Fabric API for the Minecraft version shown in the release notes, then download the `ConfigStackMC-...-fabric.jar` file.
+
+### Singleplayer
 
-1. Install Fabric Loader for the Minecraft version shown in the release notes.
-2. Install Fabric API for the same Minecraft version.
-3. Download the `ConfigStackMC-...-fabric.jar` file from Releases.
-4. Put it into your local `mods/` folder.
-5. Start the game once.
-6. Open the generated config:
+1. Put the Fabric jar into your local `mods/` folder.
+2. Start the game once.
+3. Open the generated config:
 
 ```text
 config/configstackmc.yml
 ```
 
-7. Edit the stack sizes you want.
-8. Run:
+4. Edit the stack sizes you want.
+5. Run:
 
 ```text
 /stackconfig reload
 ```
 
----
-
-## Fabric installation: multiplayer server
+### Multiplayer server
 
-1. Install Fabric Loader on the server for the Minecraft version shown in the release notes.
-2. Install Fabric API on the server for the same Minecraft version.
-3. Download the `ConfigStackMC-...-fabric.jar` file from Releases.
-4. Put it into the server's `mods/` folder.
-5. Start or restart the server once.
-6. Open the generated config:
+1. Put the same Fabric jar into the server's `mods/` folder.
+2. Start or restart the server once.
+3. Open the generated config:
 
 ```text
 config/configstackmc.yml
 ```
 
-7. Edit the stack sizes you want.
-8. Run:
+4. Edit the stack sizes you want.
+5. Run:
 
 ```text
 /stackconfig reload
 ```
 
-The Fabric jar is for both Fabric singleplayer and Fabric multiplayer servers. Paper servers still need the Paper jar instead.
-
 ---
 
-## Config example
+## ⚙️ Configuration
 
 Paper config path:
 
@@ -168,6 +184,7 @@ Default config uses normal vanilla values. It is safe to install without changin
 ```yaml
 max-allowed-stack-size: 99
 warn-dangerous-items: true
+
 items:
   dried_ghast: 64
   bell: 64
@@ -187,6 +204,7 @@ Example edited config:
 ```yaml
 max-allowed-stack-size: 99
 warn-dangerous-items: true
+
 items:
   ender_pearl: 64
   snowball: 64
@@ -205,9 +223,24 @@ Item id rules:
 - Invalid item names are ignored with a warning instead of crashing the server/game.
 - Stack sizes must be from `1` to the safe API limit, currently `99`.
 
+### Modded items
+
+On Fabric, modded items should work as long as you use their full item id:
+
+```yaml
+items:
+  create:brass_ingot: 64
+  farmersdelight:tomato: 32
+  another_mod:custom_item: 16
+```
+
+The part before `:` is the mod id. Leaving it out makes ConfigStackMC treat the item as a normal `minecraft:` item.
+
+Paper does not have true Fabric/Forge mod items. Custom items added by Paper plugins are usually based on a vanilla material, so ConfigStackMC may only see the base item instead of that custom item by itself.
+
 ---
 
-## Commands
+## ⌨️ Commands
 
 | Command | Permission | What it does |
 | --- | --- | --- |
@@ -223,9 +256,12 @@ Examples:
 /stackconfig info minecraft:totem_of_undying
 ```
 
+> [!IMPORTANT]
+> After using `/stackconfig reload` or `/stacks reload`, some existing stacks may not update instantly. Reopen the inventory, reconnect, or restart the server/singleplayer world if needed.
+
 ---
 
-## What ConfigStackMC changes
+## 🎒 What ConfigStackMC changes
 
 ConfigStackMC only changes the max stack size of configured items.
 
@@ -242,7 +278,7 @@ Minecraft still decides whether two item stacks are compatible. For example, two
 
 ---
 
-## Notes about special items
+## ⚠️ Notes about special items
 
 Be careful when increasing stack sizes for items that can store special data, such as:
 
@@ -258,48 +294,20 @@ ConfigStackMC does not block them, but stacking data-heavy items can have gamepl
 
 ---
 
-## Troubleshooting
-
-### Paper says the jar has no `plugin.yml` or `paper-plugin.yml`
-
-You probably placed the wrong file in `plugins/`.
-
-Use the file with `paper` in its name:
-
-```text
-ConfigStackMC-...-paper.jar
-```
-
-Do not use the Fabric jar on Paper.
+## 🧯 Troubleshooting
 
-### Fabric does not load the mod
+Most problems are caused by using the wrong jar or mixing versions.
 
-Check that you installed:
+- **Paper server:** use the jar with `paper` in its name and place it in `plugins/`.
+- **Fabric:** use the jar with `fabric` in its name, place it in `mods/`, and make sure Fabric Loader and Fabric API match the Minecraft version shown in the release.
+- **Config changes are not showing:** run `/stackconfig reload`, then reopen the inventory or reconnect. Existing stacks may need a server or world restart.
+- **Still not loading:** check the first ConfigStackMC warning or error in the server/game log. It usually points directly to the problem.
 
-- the Minecraft version shown in the release notes
-- Fabric Loader for that version
-- Fabric API for that version
-- the `ConfigStackMC-...-fabric.jar` file
-
-### Nothing changed after editing the config
-
-Run:
-
-```text
-/stackconfig reload
-```
-
-Then check an item:
-
-```text
-/stackconfig info ender_pearl
-```
-
-Also make sure the item is listed under `items:` and that the number is valid.
+Still stuck or found a bug? [Open an issue](https://github.com/TheETR/ConfigStackMC/issues/new) and include your Minecraft version, platform, ConfigStackMC version, and the relevant log or error message.
 
 ---
 
-## For developers
+## 👨‍💻 For developers
 
 Most users do not need to build this project. Download a jar from Releases instead.
 
@@ -332,9 +340,8 @@ The release workflow supports:
 - automatic daily checks for new compatible targets
 - release tags like `v1.0.0-mc26.1.2`
 
-
 ---
 
-## License
+## 📜 License
 
 All rights reserved unless a separate license file says otherwise.