Piston Scanner

本次更新对活塞诊断面板的UI结构进行了全面重构，将原有功能整合为三大可切换大类，同时引入纯缓存监听式扫描算法，彻底改变了系统的性能表现和工作方式。This update completely restructures the piston diagnosis panel UI, consolidating existing features into three switchable main categories while introducing a pure cache-and-listener-based scanning algorithm, fundamentally transforming system performance and workflow.

新的UI布局在诊断面板顶部设置了三个并列的大类标签，分别是单方块搜索、故障列表和可视化检测模式，玩家可随时点击切换。原有搜索与分组浏览功能归入单方块搜索大类，而区域筛选与定位功能保持不变且适用于所有大类，确保玩家在不同模式下都能快速锁定目标位置。The new UI layout places three side-by-side category tabs at the top of the diagnosis panel: Single-Block Search, Fault List, and Visual Detection Mode, which players can click to switch at any time. The original search and grouped browsing features are now under the Single-Block Search category, while area filtering and positioning functions remain unchanged and apply to all categories, ensuring players can quickly locate targets in any mode.

第一大类为单方块搜索，该模式无需框选区域即可使用。玩家只需输入方块名称，系统便会在全局缓存的活塞中搜索，筛选出前方紧邻该方块的所有活塞，结果列表会显示每个活塞的坐标、激活状态和机械状态。搜索栏支持中文、拼音全拼、拼音首字母和英文四种输入方式，搜索结果按活塞前方的方块类型自动分组，组内按距离排序。点击任一结果，目标活塞处会生成金色透视高亮轮廓并显示坐标提示，方便玩家快速定位。The first category is Single-Block Search, which requires no area selection. Players simply enter a block name, and the system searches through all globally cached pistons, filtering out those immediately in front of the specified block. The result list shows each piston's coordinates, activation state, and mechanical state. The search bar supports Chinese, full Pinyin, Pinyin initials, and English input methods. Search results are automatically grouped by the block type in front of each piston, sorted by distance within each group. Clicking any result generates a golden see-through highlight outline at the target piston and displays coordinate hints for quick navigation.

第二大类为故障列表，同样无需框选区域。系统遍历全局缓存的所有活塞，自动执行可推动性检测，将所有无法正常推动前方方块的活塞列为故障，并在列表中优先置顶显示。每个故障条目包含坐标、故障原因分类和前方方块链详情。点击故障活塞后，界面会展示从活塞基座正前方第一个方块开始、沿推动方向依次排列的最多12个方块的具体名称和类型，系统会自动扫描并用红色高亮标记导致失败的关键方块，同时附上对应的失败原因文本。失败原因完全匹配1.19.4规则，分为不可推动方块、推动即破坏方块和物理规则限制三类，其中物理规则限制包括连锁超限、边界限制、状态冲突和时序过短等具体情形，并特别注明潜影盒可正常推动、带釉陶瓦只能推不能拉、重力方块可推但拉回时会下落等细节。The second category is Fault List, which also requires no area selection. The system iterates through all globally cached pistons, performs automatic pushability detection, and flags every piston that cannot properly push the block in front of it as faulty, displaying them at the top of the list with priority. Each fault entry includes coordinates, fault cause classification, and detailed front block chain information. After clicking a faulty piston, the interface displays the names and types of up to 12 blocks arranged in the push direction, starting from the first block directly in front of the piston base. The system automatically scans and highlights the critical block that causes the failure in red, along with the corresponding failure reason text. Failure reasons fully comply with 1.19.4 rules and are divided into three categories: Unpushable Blocks, Break-on-Push Blocks, and Physical Rule Restrictions, with the latter including chain overrun, boundary limits, state conflicts, and insufficient timing. Special notes indicate that shulker boxes can be pushed normally, glazed terracotta can only be pushed not pulled, and gravity-affected blocks can be pushed but will fall when pulled back.

第三大类为可视化检测模式，该模式必须框选区域后方可启用，否则标签显示为灰色不可用状态。框选后进入该大类，玩家可在两个子模式中选择。激活状态可视化模式下，UI界面自动关闭，框选区域内的ON活塞显示绿色高亮边框，OFF活塞显示红色高亮边框。机械状态可视化模式同理，伸出状态的活塞显示绿色边框，收回状态显示红色边框，帮助玩家直观感知区域内所有活塞的工作状态。The third category is Visual Detection Mode, which can only be activated after an area is selected; otherwise the tab appears greyed out. After selection, entering this category allows players to choose between two sub-modes. In Activation State Visualization mode, the UI automatically closes, and ON pistons within the selected area display a green highlight border while OFF pistons show a red border. In Mechanical State Visualization mode, extended pistons show a green border and retracted pistons show a red border, helping players intuitively perceive the working status of all pistons in the area.

本次更新的核心性能优化在于彻底摒弃传统遍历世界方块或遍历已加载区块的扫描方式，采用纯缓存加事件监听的架构。系统维护专用活塞缓存列表，仅记录玩家放置或操作后仍存在的活塞，每个条目包含坐标、类型、激活状态、机械状态、前方方块链快照和更新时间戳。系统注册方块放置、破坏和更新事件的监听器，当玩家放置或破坏活塞时自动增删缓存条目，当活塞因红石信号变化而动作时仅更新对应条目的状态字段。为了快速定位，系统维护以坐标哈希值为键的查找表，事件触发时可在常数时间内找到对应条目。每次变更分配版本号，扫描时直接读取缓存数据，完全不访问世界方块，扫描耗时与缓存条目数量成正比，与整个世界大小或已加载区块数量无关。所有监听器回调在独立后台线程执行，不阻塞主线程，确保游戏画面流畅。若出现缓存不一致，玩家可通过按键触发轻量级世界扫描来手动重建缓存，该操作同样在后台进行。The core performance optimization of this update is the complete abandonment of traditional scanning methods that iterate through world blocks or loaded chunks, adopting a pure cache-plus-event-listener architecture. The system maintains a dedicated piston cache list that only records pistons placed or operated by players and still existing. Each entry contains coordinates, type, activation state, mechanical state, front block chain snapshot, and update timestamp. The system registers listeners for block placement, destruction, and update events, automatically adding or removing cache entries when players place or break pistons, and only updating the status fields of corresponding entries when pistons act due to redstone signal changes. For fast lookup, the system maintains a hash table keyed by coordinate hash values, allowing constant-time retrieval of corresponding entries upon event triggers. Each change is assigned a version number. Scans directly read cache data without ever accessing world blocks, making scan time proportional to the number of cached entries and independent of total world size or loaded chunk count. All listener callbacks execute on dedicated background threads, never blocking the main thread, ensuring smooth game rendering. In case of cache inconsistency, players can trigger a lightweight world scan via a keybind to manually rebuild the cache, with the operation also running in the background.

UI列表功能得到全面增强，支持多级组合排序，可按故障状态、激活状态、机械状态和距离依次排列，同时新增过滤器下拉菜单，可快速筛选全部活塞、仅故障、仅正常、仅伸出或仅收回状态。前方方块链改为横向方块图标条展示，每个位置显示对应游戏纹理缩略图，故障方块周围添加红色脉冲动画边框，图标下方显示方块名称和失败原因。在详情面板点击方块图标或列表条目，游戏世界中对应活塞会生成持续显示的透视高亮轮廓，绿色代表正常，红色代表故障，高亮不会自动消失，直至玩家手动取消或再次点击关闭，以此表明已发现并处理该位置。所有操作按键均支持在游戏控制设置中重新绑定。面板底部新增性能状态条，实时显示扫描耗时、缓存活塞总数、监听事件触发总次数、最后更新来源以及后台任务队列积压长度。UI list functionality has been significantly enhanced with multi-level combined sorting, allowing ordering by fault status, activation state, mechanical state, and distance. A new filter dropdown lets players quickly select All Pistons, Faulty Only, Normal Only, Extended Only, or Retracted Only. The front block chain is now displayed as a horizontal strip of block icons, with each position showing the corresponding game texture thumbnail, and faulty blocks surrounded by a red pulsing animation border, with the block name and failure reason shown below the icon. Clicking a block icon or list entry in the detail panel generates a persistent see-through highlight outline on the corresponding piston in the game world, green for normal and red for faulty. The highlight does not disappear automatically until manually cancelled or toggled off by clicking again, indicating that the location has been identified and addressed. All action keybinds are fully rebindable in the game control settings. A new performance status bar is added at the bottom of the panel, displaying in real time scan duration, total cached piston count, total listener event trigger count, last update source, and background task queue backlog length.

本次更新适用于红石电路调试、隐藏机关发现、大型红石项目管理、故障精准诊断、服务器卡顿排查以及性能敏感环境下的持续监控，所有新增功能与现有扫描定位系统无缝集成，为玩家提供从扫描、监控、诊断到性能优化的全方位活塞管理解决方案。This update is applicable to redstone circuit debugging, hidden trap discovery, large-scale redstone project management, precise fault diagnosis, server lag troubleshooting, and continuous monitoring in performance-sensitive environments. All new features integrate seamlessly with the existing scan-and-locate system, providing players with a comprehensive piston management solution covering scanning, monitoring, diagnosis, and performance optimization.