Chiseled Bookshelf Searcher

---

### 📖 Mod Introduction

Chiseled Bookshelf Searcher is a lightweight Fabric client-side mod designed for Minecraft 1.20+. It addresses the pain point of quickly finding specific books once you have many Chiseled Bookshelves. Simply press the shortcut key, enter a keyword, and the mod will automatically scan all nearby Chiseled Bookshelves, using dazzling visual effects to guide you directly to the target book's location.

Whether it's enchanted books, written books, or book and quills, whether you search in Chinese or using Pinyin initials, it handles everything with ease. Say goodbye to the hassle of rifling through bookshelves one by one, and make book management efficient and elegant.

---

### ✨ Core Features

**Intelligent Search System**

Press the default shortcut key Z to open the clean search interface. Enter a book name, enchantment name, or their Pinyin initials, and search results will display matching books in real time, along with the world coordinates and relative distance of their bookshelves. The search supports fuzzy matching – entering "保护" (Protection), "baohu", or even "bh" will find the "保护 IV" (Protection IV) enchanted book. For books with identical names, all matching bookshelf positions will be listed and sorted by distance from nearest to farthest.

**Visual Guidance Effects**

After clicking a search result, the game will instantly trigger two visual guidance effects. The target Chiseled Bookshelf will be enveloped in a translucent blue light curtain, surrounded by a bright blue highlighted wireframe that remains clearly visible even if the bookshelf is completely blocked by other blocks. The top of the screen will also display the currently tracked book name and target coordinates. All effects will automatically disappear once you walk close to the bookshelf.

**Automatic Caching Mechanism**

The mod automatically scans all Chiseled Bookshelves within loaded chunks around the player in the background, persistently saving book information to a local configuration file. Even after exiting and restarting the game, previous scan records are not lost. The cache updates in real time whenever a book is inserted or removed, ensuring search result accuracy. The scanning process runs efficiently in the background with negligible impact on game performance.

**Fully Client-Side Operation**

This mod runs entirely on the client side and does not need to be installed on the server. Even when playing on multiplayer servers, you can still use all features normally. However, please note that on servers, since the client cannot directly access server-side bookshelf data, the mod will automatically switch to a data retrieval method limited to single-player use. For the full experience, it is recommended to use the mod in single-player worlds or LAN games.

---

### 🎮 How to Use

Place any number of Chiseled Bookshelves in the game and insert books into them. Press the Z key to open the search interface, and enter the book name or enchantment name you remember in the input box (supports Pinyin and Pinyin initials). Search results will display each book's name, the Chinese name of its dimension, exact coordinates, and its distance from you.

Click on any search result, and the game will automatically guide you to that bookshelf. Follow the purple navigation line and blue highlight box to easily locate it. After walking within about 1.5 blocks of the bookshelf, the guidance effects will disappear automatically. You can also press ESC at any time to cancel guidance, or click on a new search result to switch targets.

---

### ⚙️ Configuration & Customization

The shortcut key can be freely remapped in the game's settings under "Controls" → "Chiseled Bookshelf Searcher" category. The cache file is located at `config/bookshelf_searcher_cache.json` in the game directory and can be manually deleted to clear the cache. The mod's language follows the game's language settings and currently supports Simplified Chinese and English.

---

### 📦 Installation Requirements

Minecraft version 1.20+ is required, along with Fabric Loader 0.14.21 or above, and Fabric API. The mod does not require any other prerequisites or dependencies. Simply place the mod file into the `.minecraft/mods/` folder to use it.

---

### 💡 Notes

The search range covers loaded areas within a radius of 5 chunks (approximately 80 blocks) centered on the player. Bookshelves beyond this range will not be scanned. When playing on a server, make sure the chunk containing the target bookshelf is loaded; otherwise, guidance will automatically cancel with a "Target chunk not loaded" prompt. Guidance effects are visible only to you and cannot be seen by other players. Only one active guidance target can exist at a time; clicking a new result will automatically override the previous one.

Chinese:

Chiseled Bookshelf Searcher - 雕纹书架搜索器

### 📖 模组简介

Chiseled Bookshelf Searcher 是一款轻量级的 Fabric 客户端模组，专为 Minecraft 1.20+设计。它解决了雕纹书架（Chiseled Bookshelf）数量增多后难以快速找到特定书本的痛点。只需按下快捷键，输入关键词，模组便会自动扫描周围所有雕纹书架，并以绚丽的视觉特效引导你直达目标书本所在的位置。

无论是附魔书、成书还是书与笔，无论是中文搜索还是拼音首字母搜索，都能轻松应对。从此告别逐个翻找书架的烦恼，让书本管理变得高效而优雅。

---

### ✨ 核心功能

**智能搜索系统**

按下默认快捷键 Z 键即可打开简洁的搜索界面。输入书本名称、附魔名称或它们的拼音首字母，搜索结果会实时显示匹配的书本及其所在书架的世界坐标和相对距离。搜索支持模糊匹配，输入"保护"或"baohu"甚至"bh"都能找到"保护 IV"附魔书。同名书本会列出所有匹配的书架位置，并按距离由近到远排序。

**视觉引导特效**

点击搜索结果后，游戏内会立刻触发两种视觉引导效果。目标雕纹书架将被蓝色半透明光幕包裹，同时环绕着明亮的蓝色高亮线框，即使书架被其他方块完全遮挡也能清晰透视可见。屏幕上方还会显示当前追踪的书名和目标坐标，走到书架附近后所有特效自动消失。

**自动缓存机制**

模组会在后台自动扫描玩家周围已加载区块内的所有雕纹书架，并将书本信息持久化保存到本地配置文件。即使退出游戏重新进入，之前的扫描记录也不会丢失。每次放入或取出书本时缓存会实时更新，确保搜索结果的准确性。扫描过程在后台高效运行，对游戏性能的影响几乎可以忽略不计。

**完全客户端运行**

本模组完全在客户端运行，无需在服务端安装。即使是在多人服务器上游玩，你仍然可以正常使用所有功能。不过需要注意的是，在服务器上由于客户端无法直接获取服务端的书架数据，模组会自动切换为仅限单人游戏使用的数据获取方式。建议在单人世界或局域网联机中使用以获得完整体验。

---

### 🎮 使用方法

在游戏中放置任意数量的雕纹书架并放入书本。按下 Z 键打开搜索界面，在输入框中输入你记得的书名或附魔名（支持拼音和拼音首字母）。搜索结果会显示每本书的名称、所在维度的中文名、精确坐标以及与你的距离。

点击任意搜索结果，游戏便会自动引导你前往该书架。跟随紫色导航线和蓝色高亮框即可轻松定位。走近书架约 1.5 格范围内后，引导特效自动消失。你也可以随时按 ESC 取消引导，或点击新的搜索结果切换目标。

---

### ⚙️ 配置与自定义

快捷键可在游戏设置中的"按键设置"→"雕纹书架搜索器"分类下自由修改。缓存文件位于游戏目录的 `config/bookshelf_searcher_cache.json`，可手动删除以清空缓存。模组语言跟随游戏语言设置，目前支持简体中文和英文。

---

### 📦 安装要求

Minecraft 版本需为 1.20+，需安装 Fabric Loader 0.14.21 及以上版本，以及 Fabric API。模组无需任何其他前置或依赖。直接将模组文件放入 `.minecraft/mods/` 文件夹即可使用。

---

### 💡 注意事项

搜索范围是以玩家为中心半径 5 个区块（约 80 格）内的已加载区域，超出范围的书架不会被扫描到。在服务器上游玩时，请确保目标书架所在区块已加载，否则引导会自动取消并提示"目标区块未加载"。引导特效仅自己可见，其他玩家无法看到。同一时间只能有一个激活的引导目标，点击新的结果会自动覆盖旧的。