# Piston Scanner & Locator System

## Mod Overview

**Piston Scanner & Locator System** is a lightweight client-side helper mod designed for redstone engineers and survival builders. It quickly scans all pistons within loaded chunks around the player and provides an intuitive graphical interface for categorized browsing, pinyin-based search, area filtering, and one-click navigation, making complex redstone circuit troubleshooting effortless.

## Core Features

### One-Key Scan
Press the **X key** to instantly scan all pistons within currently loaded chunks. The mod uses an optimized scanning algorithm with a chunk section pre-check mechanism to skip empty areas rapidly. Even at high render distances, scans complete within milliseconds without causing game lag. The graphical interface will automatically open to display all results after scanning.

### Cuboid Region Selection
Press the **Z key** to select the block under your crosshair as a region vertex. The first Z press selects the first vertex, and the second Z press selects the second vertex—these two points define a cuboid space. Once the region is set, subsequent X-key scans will only search for pistons within this cuboid area. Pistons whose base block lies inside the region are included, even if their piston head extends outside. The region is highlighted with a semi-transparent light green wireframe, with visible marker blocks at all eight vertices for easy range confirmation. Press Z a third time or press the **C key** to clear the selection and disable the wireframe rendering.

### Smart Categorization
Scan results are automatically divided into four types:
- **Inactive Regular Pistons** – Retracted regular pistons
- **Active Regular Pistons** – Extended regular pistons
- **Inactive Sticky Pistons** – Retracted sticky pistons
- **Active Sticky Pistons** – Extended sticky pistons

Real-time counts for each type are displayed on the interface, allowing quick insight into the piston distribution across the scanned area.

### Pinyin Search
The search bar supports multiple input methods, eliminating the hassle of switching keyboard layouts:
- **Chinese search**: Enter Chinese block names directly, e.g., "石头" (stone) or "活塞" (piston)
- **Full pinyin**: Type "shitou" or "huosai" to match the corresponding Chinese names
- **Pinyin initials**: Enter "st" to match "石头" (stone), or "hs" to match "活塞" (piston)
- **English search**: Supports English registry names like "stone" or "piston"

### Dropdown Type Filter
A type-filter dropdown menu is located at the top of the interface. Click to quickly switch between "All Types" and any of the four piston categories. The result list updates in real time while preserving the current search text, enabling precise cross-filtering.

### Grouped Browsing
Search results are automatically grouped by the type of block in front of each piston. Pistons pushing the same block type are placed in the same group. Click a group header to expand and view detailed information for all pistons within that group. Each group displays the distance to the nearest piston, and pistons within each group are sorted from nearest to farthest, helping you quickly locate the closest ones.

### One-Click Locate & Visual Guidance
Click any search result entry, and the mod instantly triggers location guidance:
- A **golden, see-through highlight outline** appears at the target piston's position, visible through all blocks
- The highlight features a fade animation, transitioning from gold to red over time
- A guidance message appears at the top of the screen, displaying the piston type and exact coordinates
- The highlight and message remain visible until the player comes within **3 blocks** of the target, at which point they disappear automatically

### Smart Guidance Tracking
Once location guidance is activated, the mod continuously monitors the target's status:
- When the player approaches within 3 blocks, the highlight and message disappear automatically, with an arrival notification displayed
- If the target piston is destroyed, a notification appears and the guidance is cleared
- If the target chunk is unloaded, a notification appears and the guidance is cleared
- Guidance stops automatically when crossing dimensions

## Use Cases

**Redstone Circuit Debugging**: Quickly locate all pistons in your world and see their states at a glance. Whether troubleshooting complex automatic doors, sugarcane farms, or cobblestone generators, you can instantly find every piston.

**Finding Hidden Mechanisms**: Search by the block type in front of pistons to uncover hidden doors, traps, or secret passages. Enter "石头" or "shitou" to find all pistons pushing stone blocks, easily locating concealed entrances.

**Large-Scale Redstone Project Management**: Track piston counts and distribution across your builds. Use the region selection feature to constrain scans to specific areas for accurate statistics.

**Server Maintenance & Lag Investigation**: Scan for piston quantities within loaded chunks to quickly identify sources of lag caused by excessive pistons. Combine with region selection to check suspicious areas one by one.

**Survival Building Assistance**: In survival mode, quickly verify that all pistons are placed correctly in automatic farms, avoiding missed or misplaced blocks.

## Technical Specifications

- Pure client-side mod – no server installation required; works in both single-player and multiplayer
- Built on Fabric API, compatible with most mainstream Fabric mods
- Supports Minecraft 1.19.4
- Full bilingual support (Chinese/English), automatically switching based on game language settings
- All keybindings can be customized in the Controls settings menu
- Scanning algorithm is deeply optimized to prevent game lag
- Highlight rendering uses the same stable technical solution as Litematica

## Installation

1. Ensure Fabric Loader 0.14.21 or higher is installed
2. Install the Fabric API mod
3. Place the mod's JAR file into the `mods` folder of your game directory
4. Launch the game – press the X key by default to open the scan interface and get started

## Operation Guide

Press the **X key** to open the scan interface and perform an automatic scan. Once the interface appears, type in the search box for real-time filtering – supports Chinese, full pinyin, pinyin initials, and English. Click the "Type" button to open the dropdown menu and switch between "All Types" and the four piston categories. Scan results are displayed in groups by the block type in front of each piston – click a group header to expand and view all pistons in that group, and click again to collapse. Click a specific piston entry to activate location guidance, generating a golden highlight outline at the target position with coordinate hints. Click the "Refresh" button to rescan the current area, or click "Close" or press Esc to exit the interface.

For region selection, press the **Z key** to select the block under your crosshair. The first Z press selects the first vertex, and the green wireframe begins to appear. The second Z press selects the second vertex, completing the region with a fully displayed green wireframe. Press Z a third time or press the **C key** to clear the selection and disable wireframe rendering.

Use the mouse scroll wheel to browse up and down through the list. When results exceed the visible area, a scrollbar appears on the right to indicate your current position. Once location guidance is active, simply move toward the target piston – the highlight and message will disappear automatically as soon as you come within 3 blocks, with no additional actions required.

# 活塞扫描与定位系统 (Piston Scanner)

## 模组简介

**活塞扫描与定位系统**是一款专为红石工程师和生存建筑玩家打造的轻量级客户端辅助模组。它能快速扫描玩家周围加载区块内的所有活塞，提供直观的图形界面进行分类浏览、拼音搜索、区域筛选和一键定位导航，让复杂的红石电路排查工作变得轻松高效。

## 核心功能

### 一键扫描
按下**X键**即可瞬间扫描当前加载区块内的所有活塞。模组采用优化的扫描算法，通过区块Section预检机制快速跳过空区域，即使在高渲染距离下也能在毫秒级内完成扫描，不会造成游戏卡顿。扫描完成后会自动弹出图形界面展示所有结果。

### 立方体区域选择
按下**Z键**可以选取准星指向的方块作为区域顶点。第一次按Z选择第一个顶点，第二次按Z选择第二个顶点，两个顶点将框定一个立方体空间。区域选定后，再次按X键扫描时将仅搜索该立方体区域内的活塞，活塞本体在区域内即会被扫描到，活塞头伸出区域外不受影响。区域会以淡绿色半透明线框高亮显示，八个顶点带有醒目的小方块标记，方便确认范围。第三次按Z键或按C键即可清除选择区域并关闭边框渲染。

### 智能分类
扫描结果自动分为四种类型：
- **未激活的普通活塞** - 处于收回状态的普通活塞
- **激活的普通活塞** - 处于伸出状态的普通活塞
- **未激活的粘性活塞** - 处于收回状态的粘性活塞
- **激活的粘性活塞** - 处于伸出状态的粘性活塞

每种类型的数量都会在界面上实时统计显示，方便快速了解当前区域的活塞分布情况。

### 拼音搜索
搜索栏支持多种输入方式，彻底告别切换输入法的烦恼：
- **中文搜索**：直接输入"石头"、"活塞"等中文方块名
- **拼音全拼**：输入"shitou"、"huosai"即可匹配对应中文名称
- **拼音首字母**：输入"st"可匹配"石头"，"hs"可匹配"活塞"
- **英文搜索**：支持方块英文注册名如"stone"、"piston"的搜索

### 下拉类型筛选
界面上方设有类型筛选下拉菜单，点击可在"全部类型"和四种活塞类型间快速切换。筛选后列表实时刷新并保留当前搜索文本，实现精准的交叉过滤。

### 分组浏览
搜索结果按活塞前方的方块类型自动分组。推动同一类型方块的活塞归为一组，点击分组标题可展开查看组内所有活塞的具体信息。每组显示距离玩家最近活塞的距离，组内活塞按距离由近到远排列，帮助快速定位最近的活塞。

### 一键定位与视觉引导
点击任意搜索结果项，模组会立即触发定位引导：
- 在目标活塞位置生成**金色透视高亮轮廓**，穿透所有方块清晰可见
- 高亮轮廓带有渐隐动画，颜色会从金色逐渐过渡到红色
- 屏幕上方显示定位提示文字，标明活塞类型和精确坐标
- 高亮和提示会持续显示，直到玩家靠近目标**3格以内**时自动消失

### 智能引导追踪
定位激活后，模组会持续监测目标状态：
- 玩家靠近目标3格以内时，高亮和提示自动消失，并显示到达提示
- 目标活塞被破坏时，自动显示提示并清除定位
- 目标区块被卸载时，自动显示提示并清除定位
- 跨维度时自动停止引导

## 使用场景

**排查红石电路**：快速定位地图中所有活塞的位置和状态，一目了然掌握电路布局。无论是调试复杂的自动门、甘蔗机还是刷石机，都能迅速找到每个活塞。

**寻找隐藏机关**：通过搜索活塞前方方块类型，反向发现隐藏的门、陷阱或密道。输入"石头"或"shitou"即可找到所有推动石头的活塞，轻松定位隐藏入口。

**大型红石工程管理**：在建造大型红石机械时，快速统计项目中的活塞数量和分布。通过区域选择功能限定扫描范围，精准统计特定区域的活塞。

**服务器维护与卡顿排查**：扫描加载区块内的活塞数量，快速排查因大量活塞造成的卡顿源头。结合区域选择功能，逐一排查可疑区域。

**生存建筑辅助**：在生存模式中建造自动农场时，快速确认所有活塞是否按设计放置，避免遗漏或错误放置。

## 技术特性

- 纯客户端模组，无需在服务端安装，单人游戏和多人服务器均可使用
- 基于Fabric API开发，兼容大多数主流Fabric模组
- 支持Minecraft 1.19.4版本
- 完整的中英文双语支持，根据游戏语言设置自动切换
- 所有按键绑定均可在控制设置中自定义修改
- 扫描算法经过深度优化，不会造成游戏卡顿
- 高亮渲染采用Litematica同款技术方案，稳定可靠

## 安装方法

1. 确保已安装Fabric Loader 0.14.21或更高版本
2. 安装Fabric API模组
3. 将本模组的jar文件放入游戏目录的mods文件夹
4. 启动游戏，默认按X键打开扫描界面开始使用

## 操作说明

按**X键**打开扫描界面并自动执行扫描。界面弹出后，可在搜索框中输入文字进行实时过滤，支持中文、拼音全拼、拼音首字母和英文。点击"类型"按钮可打开下拉菜单，在全部类型和四种活塞类型间切换。扫描结果按前方方块类型分组显示，点击分组标题可展开查看组内所有活塞，再次点击则折叠。点击具体的活塞条目会触发定位引导，在目标位置生成金色高亮轮廓并显示坐标提示。点击"刷新"按钮可重新扫描当前区块，点击"关闭"按钮或按Esc键退出界面。

区域选择方面，按**Z键**可选取准星指向的方块。第一次按Z选择第一个顶点，此时绿色边框开始显示。第二次按Z选择第二个顶点，区域框选完成，绿色边框完整显示。第三次按Z或按**C键**清除选择区域并关闭边框渲染。

鼠标滚轮可在列表中上下滚动浏览，当结果超出界面显示范围时右侧会出现滚动条指示当前位置。定位引导激活后，只需向目标活塞移动，到达3格范围内高亮和提示即自动消失，无需任何额外操作。