From 5923fb5077e2c4adad387474aae003f9c66e55e2 Mon Sep 17 00:00:00 2001
From: Robbie Gordon <99526923+ASAOddball1@users.noreply.github.com>
Date: Sat, 7 Mar 2026 22:54:46 -0800
Subject: [PATCH] Update README.md

---
 README.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 44183d4..88948b9 100644
--- a/README.md
+++ b/README.md
@@ -85,6 +85,14 @@ When you run Auto-Sync, add the folder containing these files as part of your li
 
 ## Known Limitations
 
+### Block and Item Texture Folder Conflicts
+Java Edition texture packs store **block textures** and **item textures** in separate subfolders (textures/block/ and textures/item/), and some filenames are shared between the two — for example a block and its item drop can have the exact same filename. Because of this, when running Auto-Sync you should point your library at the specific subfolder you are building for rather than the root of the pack:
+
+For **terrain builds** — browse to the **textures/block/** folder
+For **item builds** — browse to the **textures/item/** folder
+
+If you point the library at the pack root or the textures/ folder, block textures can end up being placed in item slots and vice versa wherever filenames collide.
+
 ### Particles Sheet
 The particles JSON mapping file is **not yet available**. The Particles tab is present in the tool but cannot be used to generate a sheet until the mapping file is added in a future update.
 
@@ -121,7 +129,7 @@ python MLCE_Converter.py
 ## How to Use
 
 ### Step 1 — Select your library
-Click **SELECT LIBRARY** and browse to the root folder of a Java Edition texture pack (or any folder containing `.png` files). The tool walks all subfolders automatically. To include the bundled MLCE-exclusive textures, point it at the root of this repo or a folder that contains them alongside your pack files.
+Click **SELECT LIBRARY** and browse to the textures folder for Blocks and the items folder inside of the textures for Items of a Java Edition texture pack (or any folder containing the correct `.png` files). (the reason for needing different folders for block textures and items is because some of the blocks have the same filename as the item sprite because its in a different folder than the item sprite causing the block textures to be placed in the space of the item sprite) The tool walks all subfolders automatically. To include the bundled MLCE-exclusive textures, point it at the root of this repo or a folder that contains them alongside your pack files.
 
 ### Step 2 — Load a JSON
 Click **TERRAIN JSON**, **ITEMS JSON**, or **PARTICLES JSON** and select the corresponding mapping file from this repo. The entry list will populate immediately.