Piston Scanner

Piston Scanner 是一款辅助玩家快速扫描、诊断和管理活塞的客户端模组（支持1.19.2/1.19.4，需Fabric），旨在为红石调试、大型项目维护和性能监控提供一站式解决方案。

Piston Scanner is a client-side mod (for 1.19.2/1.19.4, requires Fabric) that helps players quickly scan, diagnose, and manage pistons. It provides an all-in-one solution for redstone debugging, large-project maintenance, and performance monitoring.

核心机制：纯缓存监听架构。彻底摒弃传统遍历世界方块的扫描方式，采用纯缓存加事件监听架构：系统维护专用活塞缓存列表，仅记录玩家放置或操作后仍存在的活塞。通过监听方块放置、破坏和更新事件，实时增删或更新缓存条目，配合坐标哈希查找表实现常数级定位。扫描耗时仅与缓存活塞数量成正比，与世界大小或加载区块数量无关，所有监听回调在后台线程执行，不阻塞主游戏画面。

Core Mechanism: Pure Cache plus Event Listener Architecture. Completely abandons the traditional approach of scanning the entire world. Instead, it maintains a dedicated piston cache list that only records pistons still existing after being placed or operated by the player. By listening to block place, break, and update events, it adds, removes, or updates cache entries in real time. With a coordinate-hash lookup table, positioning is constant-time. Scanning time is proportional only to the number of cached pistons, independent of world size or loaded chunks. All listener callbacks run on background threads and never block the main game loop.

三大诊断面板（v3.0 UI重构）。面板顶部设三个并列大类标签，区域筛选与定位功能适用于所有模式：

Three Diagnostic Panels (v3.0 UI Redesign). Three category tabs are placed side by side at the top. Area filtering and positioning work in all modes:

单方块搜索（无需框选）：输入方块名称（支持中文/拼音全拼/首字母/英文），全局搜索所有紧邻该方块前方的活塞。结果按前方方块类型分组、按距离排序，显示坐标、激活/机械状态。点击条目，目标活塞生成金色透视高亮轮廓及坐标提示。

Single-Block Search (no selection needed): Enter a block name (supports Chinese, full Pinyin, Pinyin initials, or English). Globally searches all pistons directly in front of that block. Results are grouped by the block in front and sorted by distance, showing coordinates, activation state, and mechanical state. Click an entry to highlight the target piston with a golden translucent outline and coordinate indicator.

故障列表（无需框选）：自动遍历所有缓存活塞，执行1.19.4规则的可推动性检测，将无法正常推动前方方块的活塞置顶显示。每个故障条目含坐标、故障原因分类（不可推动/推动即破坏/物理规则限制，后者细分为连锁超限、边界冲突、时序不足等）及前方方块链详情。点击后展示最多12个方块的名称/类型，红色高亮标记关键故障方块并附失败原因（特别注明潜影盒可推、带釉陶瓦只推不拉、重力方块回拉下落等细节）。

Fault List (no selection needed): Automatically iterates through all cached pistons and runs pushability checks based on 1.19.4 rules. Pistons that cannot push the block in front are pinned to the top. Each fault entry shows coordinates, fault category (Unpushable / Breaks on Push / Physics Limitations – the latter includes chain-over-limit, boundary conflicts, timing insufficiency, etc.) and details of the front-block chain. Click to display up to 12 block names and types, with critical faulty blocks highlighted in red and failure reasons attached (notably specifying that shulker boxes are pushable, glazed terracotta can be pushed but not pulled, gravity blocks fall back when pulled, etc.).

可视化检测模式（需框选区域）：框选后切换至该模式，可选两个子模式：激活状态可视化（ON活塞绿色边框，OFF红色边框）和机械状态可视化（伸出状态绿色边框，收回红色边框）。UI自动关闭，帮助直观感知区域内所有活塞工作状态。

Visual Inspection Mode (requires a selected area): After selection, switch to this mode with two sub-options: Activation-state visualisation (ON pistons with green borders, OFF with red borders) and Mechanical-state visualisation (extended with green borders, retracted with red borders). The UI automatically closes, helping you intuitively perceive the working state of all pistons in the area.

红石储存库与列表管理（v4.0新增）。文件夹系统：可新建、重命名、移动方块至文件夹，收藏夹受保护不可删除，文件夹实时显示内含方块数。扁平列表与搜索：移除旧分类树，改为按方块名称分组的扁平列表；搜索框支持按方块名称、坐标、维度查找，搜索状态在GUI关闭后持久保留。键盘与滚动优化：方向键/Page Up-Down/Home-End控制滚动，右侧新增可视化滚动条。

Redstone Repository and List Management (v4.0 New). Folder System: Create, rename, and move blocks into folders. Favourites are protected and cannot be deleted. Each folder shows the number of blocks it contains in real time. Flat List and Search: The old category tree is removed, replaced by a flat list grouped by block name. The search box supports searching by block name, coordinates, and dimension; search state persists after the GUI is closed. Keyboard and Scrolling Optimisation: Arrow keys / Page Up-Down / Home-End control scrolling, with a new visual scrollbar on the right.

列表增强与交互：多级组合排序（可按故障状态、激活状态、机械状态、距离依次排列）。过滤器下拉菜单（快速筛选全部/仅故障/仅正常/仅伸出/仅收回）。前方方块链以横向方块图标条展示，故障方块带红色脉冲动画边框，下方显示名称和失败原因。高亮定位：点击方块图标或列表条目，世界中对应活塞生成持续透视高亮（绿色正常/红色故障），不会自动消失，需手动取消，便于标记已处理位置。所有按键支持在游戏控制设置中重新绑定。

List Enhancements and Interaction: Multi-level combined sorting (by fault state, activation state, mechanical state, and distance in sequence). Filter dropdown (quickly filter: All / Faulty Only / Normal Only / Extended Only / Retracted Only). The front-block chain is shown as a horizontal row of block icons, with faulty blocks having a red pulsing-animation border; names and failure reasons displayed below. Highlight and Locate: Click a block icon or list entry to generate a persistent outline highlight on the corresponding piston in the world (green for normal, red for faulty). The highlight does not disappear automatically; you must manually clear it, making it easy to mark positions you have already handled. All keys can be rebound in the game's control settings.

性能状态监控：面板底部新增性能状态条，实时显示扫描耗时、缓存活塞总数、监听事件触发总次数、最后更新来源、后台任务队列积压长度。

Performance Status Monitor: A new performance status bar is added at the bottom of the panel, showing scan time, total cached pistons, total listener event triggers, the last update source, and the background task queue backlog.

适用场景：红石电路调试、隐藏机关发现、大型红石项目管理、故障精准诊断、服务器卡顿排查、性能敏感环境下的持续监控。

Use Cases: Redstone circuit debugging, hidden contraption discovery, large-scale redstone project maintenance, precise fault diagnosis, server lag troubleshooting, and continuous monitoring in performance-sensitive environments.

补充说明：若缓存出现不一致，可按快捷键触发轻量级世界扫描（后台运行）手动重建。仅限客户端安装，不兼容服务端部署。默认快捷键 X（扫描界面）/ Z（选取顶点）/ C（清除选区）可能与游戏原生按键冲突，请自行调整。

Additional Notes: If the cache becomes inconsistent, you can press a hotkey to trigger a lightweight world scan (running in the background) to manually rebuild it. This is a client-only mod and is not compatible with server-side installation. Default hotkeys: X (open scan GUI) / Z (pick vertex) / C (clear selection) – they may conflict with vanilla game keys; please adjust them as needed.