Piston Scanner

# Piston Scanner / 活塞扫描器

A lightweight client-side mod for redstone engineers. Press a key to instantly scan all pistons in loaded chunks, browse them by type, search with pinyin support, and click to highlight any piston through walls.

轻量级客户端模组，一键扫描加载区块内所有活塞，支持拼音搜索、分类筛选，点击即可透视高亮定位目标活塞。

---

## Features / 功能

**One-Key Scan / 一键扫描**
Instantly scans all pistons (normal & sticky) in loaded chunks with optimized performance.

**Smart Categories / 智能分类**
Results grouped into 4 types: inactive/active × normal/sticky, with live count statistics.

**Pinyin Search / 拼音搜索**
Search by Chinese characters, full pinyin ("shitou"), initials ("st"), or English registry names — no input method switching needed.

**Grouped Results / 分组浏览**
Pistons are grouped by the block in front of them. Click to expand/collapse each group.

**Click-to-Locate / 点击定位**
Click any result to highlight the piston with a gold wireframe that glows through walls, with on-screen coordinates.

**Smart Guidance / 智能引导**
Highlight auto-clears when you approach within 3 blocks, or if the piston is destroyed/chunk unloads.

**Area Selection / 区域选择**
Press Z twice to define a cubic region; subsequent scans only search within that area. Green wireframe shows the selected region.

---

## Usage / 使用方式

| Key / 按键 | Action / 功能 |
|------------|---------------|
| **X** | Open scanner & scan / 打开扫描界面 |
| **Z** | Select block corners for area / 选取区域顶点 |
| **C** | Clear selected area / 清除选择区域 |
| **Esc** | Close GUI / 关闭界面 |

> ⚠️ **X key conflicts with vanilla "Swap Items"! Please rebind in Controls → Key Binds.**
> ⚠️ **X键与原版"交换物品"冲突！请前往 设置→按键绑定 自行调整。**

---

## Install / 安装

1. Install Fabric Loader 0.14.21+
2. Install Fabric API
3. Drop this mod's jar into `mods` folder
4. Launch and press X (or your custom keybind)

---

Compatible with Minecraft 1.19.2 / 1.19.4 | Client-side only | Bilingual (ZH/EN)