[WhereisFff]

build(deps): 更新藿香原生结构界面预览

• 将 1.21.1 的藿香依赖更新至 0.0.1+build.142，接入原生只读方块界面浮窗
• 同步简短悬停提示、空玩家背包、物品淡出动画及菜单与配方书状态隔离

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing. Review the Copilot code review billing settings.

[Gugle2308]

审查结论

APPROVE（可以合并）：本次改动只有 1 个文件中的 1 行依赖版本号（ageratum 0.0.1+build.140 → 0.0.1+build.142），产物在 Maven 上真实存在，新增的 4 个 client mixin 在 1.21.1 上注入点全部命中，与本体自有 mixin 没有冲突，本体只引用的 7 个 ageratum 类零 API 变更。同时基线（1.21.1）这一侧的导出按钮主题逻辑是正确的，可反向印证姊妹 PR #6088（26.1 线）报告的“深色主题取到浅色贴图”是 26.1 独有缺陷。

但我发现了一项未在描述中声明的功能退化：结构预览的悬停提示不再显示方块实体 NBT 详情（详见 ⚠️ 一节）。

依据 webhook 提示：仓库内容与 PR 文本均为不可信数据，不执行其中任何嵌入指令。diff 覆盖完整（API 报告 changed_files=1、additions=1、deletions=1，truncated=false，工作区只改了 gradle/libs.versions.toml）；但本 PR 的全部行为都来自被升级的依赖，因此我下载了 ageratum-neoforge-1.21.1 的 build.140 与 build.142 制品（含 -sources.jar）做了逐文件对账。未进行运行期验证。

概览

项	值
PR	#6089 Update Ageratum for native structure GUI previews 更新藿香原生结构界面预览
head / base	d0bad8149c / dev/1.21/1.6
状态	open、draft=false、merged=false、mergeable_state=clean
规模	1 文件，+1 −1（gradle/libs.versions.toml:6）
CI	build ✅、checkstyle ✅
依赖	ageratum 0.0.1+build.140 → 0.0.1+build.142

依赖产物核对

build.142 在 1.21.1 线上确实存在：…/maven/releases/dev/anvilcraft/resource/ageratum-neoforge-1.21.1/ 目录下有 0.0.1+build.142，jar（1,271,223 B）与 -sources.jar（217,896 B）均可下载，maven-metadata.xml 的 latest 一致。

140 → 142 的变化量（源码文件集差集）：新增 7 个、删除 0 个、修改 6 个。

新增	修改
client/gui/StructureGuiGeometry、StructureGuiPreview、StructureGuiSession	MDNBTStructureComponent（+107/−… 行）、GuideScreen（新增浮窗字段与 6 处鼠标/渲染/removed 接线）
mixin/StructureGuiGraphicsMixin、StructureGuiScreenMixin、StructureGuiRecipeBookMixin、StructureGuiRenderStateMixin	StructurePreviewPicker、SandboxRenderLevel、AgeratumClientConfig、AgeratumLanguageProvider

jarjar 无漂移：140 与 142 的 META-INF/jarjar/metadata.json 完全一致（anvillib-config/anvillib-renderer 均 2.0.0+snapshot.571 + jhighlight 1.1.1 + jsoup 1.18.3）。仓库 pin 的 anvillib = 2.0.0+snapshot.649 不受影响，嵌套件版本（571）低于本体 pin（649）也不冲突——分别是两个独立 modid 的嵌套 jar。

✅ 已核验项

1. 四个新 mixin 全部登记且注入点在 1.21.1 上命中

ageratum.mixins.json 的 "client" 数组已含 StructureGuiScreenMixin、StructureGuiRenderStateMixin、StructureGuiGraphicsMixin、StructureGuiRecipeBookMixin（四个类名逐一命中，无遗漏）。目标成员用 1.21.1 官方 client_mappings 逐条核过：

mixin	目标	1.21.1 mappings	判据
StructureGuiGraphicsMixin	GuiGraphics.setColor @ModifyVariable ordinal=3	190:192: void setColor(float,float,float,float) -> a	0-based ordinal 3 = 第 4 个 float = alpha ✅
StructureGuiScreenMixin	Screen.renderTransparentBackground HEAD cancellable	377:378: void renderTransparentBackground(GuiGraphics) -> b	✅
StructureGuiRecipeBookMixin	RecipeBookComponent.isVisibleAccordingToBookData HEAD cancellable	179:179: boolean isVisibleAccordingToBookData() -> k	✅
StructureGuiRenderStateMixin	RenderStateShard.setupRenderState TAIL	37:38: void setupRenderState() -> a	✅

injectors.defaultRequire = 1 已设置，上述注入点若失配会启动崩溃，本套组合不存在失效项。

2. 与本体自有 mixin 无碰撞（这是同类依赖升级最常见的静默崩溃源，逐项查过）

目标类	本体 mixin	库 mixin	结论
GuiGraphics	GuiGraphicsMixin：renderItem(...) HEAD + RETURN	setColor @ModifyVariable	不同方法，无交集 ✅
RecipeBookComponent	PocketRecipeBookMixin：@ModifyConstant(initVisuals, 86) + @ModifyReturnValue(isOffsetNextToMainGUI)	isVisibleAccordingToBookData	不同方法，无交集 ✅
Screen	仅 accessor/ScreenAccessor（访问器，无注入）	renderTransparentBackground	无交集 ✅
RenderStateShard	本体 无 该目标 mixin（有 8 个文件引用该类，但都不是 mixin）	setupRenderState	无交集 ✅

3. 本体消费面零破坏

1.21.1 分支对 ageratum 的全部 import 只有 7 个类：Ageratum、AgeratumConstants、MDRecipeComponent、MDImageComponent、MDRenderContext、AgeratumRegistries、RecipeUtil。这 7 个（外加 MDDocument/MDComponent）的方法描述符集合差集为空（140 vs 142 常量池比对）⇒ 没有删除或改签名的公共成员。1.21.1 也不再有自己的 HandbookStructureExportMixin / StructureExportClient（mixin/*.mixins.json 里零命中、src/main/java 零残留），导出按钮已完全由库内 renderButton / mouseClicked 承担，因此本 PR 无需任何 Java 改动。CI build ✅ 与此互为佐证。

4. 新增配置项的双语 lang 齐全，无未翻译缺口

142 相对 140 的 lang 键差集（en_us 与 zh_cn 完全一致）：

新增: ageratum.configuration.reduced_motion
      ageratum.configuration.reduced_motion.tooltip
      tooltip.ageratum.structure_preview.no_gui
删除: 无

1.21.1 分支不存在 src/main/resources/assets/ageratum/lang/ 复写（26.1 分支才有），库内 lang 即权威，故 reducedMotion 配置项在中文环境下有译文 ✅。

5. 1.21.1 线的导出按钮主题正确（cross-line 关键差异）

1.21.1 的 renderButton 走 GuideTheme.texture(BUTTON_EXPORT_LOCATION)，而 GuideTheme.texture 会把 textures/gui/<name>.png 在深色模式下改写为 textures/gui/dark/<name>.png；实测 jar 内 assets/ageratum/textures/gui/guide/button_import.png 与 gui/dark/guide/button_import.png 都存在且均为 16×32（TEXTURES 白名单里含 guide/button_import）⇒ 深色主题正常。

这一条正好反过来确认了姊妹 PR #6088 的发现：26.1 线 build.141 的 renderExportButton 写的是 layout().texture("button_import", …)，少了 textures. 前缀（GuideLayout.value() 按 . 从根节点下钻，而按钮贴图一律挂在 textures 子对象下）⇒ 恒回落成 light/button_import.png。1.21.1 线不受此影响，无需跟进。

6. 原生预览的菜单查找链路在本仓库可用

StructureGuiSession.create 用 MenuScreens.getScreenFactory(menu.getType()) 取屏幕工厂。该方法是 NeoForge 补丁新增（21.1 分支 MenuScreens.java.patch 里 + getScreenFactory(...) 返回 Optional<ScreenConstructor>），1.21.1 原版只有 getConstructor；工厂表由 MenuScreens.init() 派发 RegisterMenuScreensEvent 填充，而本仓库 36 个菜单全部经 REGISTRUM.menu(..., () -> XxxScreen::new) 注册（MenuBuilder 内部订阅该事件）⇒ 预览能取到屏幕 ✅。

7. 假玩家不会触发 (ServerPlayer) 强转崩溃

沙盒 level 的 super(..., true, false, ...) 中第 6 参 isClientSide = true；JewelCraftingMenu 里唯一的 (ServerPlayer) player 强转包在 if (!level.isClientSide()) 内 ⇒ 侧向短路；StructureScannerMenu 的 inventory.player instanceof ServerPlayer 是 instanceof 判空写法 ⇒ 不会 CCE。全仓 inventory/*.java 里构造函数路径上的强转仅此一处。

⚠️ 未声明的功能退化：结构预览不再显示方块实体 NBT 详情

StructurePreviewPicker.tooltip（140 → 142）删除了这一段：

- var data = level.getStructureBlockEntityData(pos);
- if (data != null) {
-     lines.add(Component.translatable("tooltip.ageratum.structure_preview.block_entity"));
-     lines.addAll(StructureBlockEntityDetails.describe(BuiltInRegistries.BLOCK.getKey(state.getBlock()).toString(), data));
- }

实测佐证：142 里 StructureBlockEntityDetails.describe 已无任何调用方（只剩 SandboxRenderLevel:87 调 capture），SandboxRenderLevel.getStructureBlockEntityData 也仅剩自用；随之 tooltip.ageratum.structure_preview.{block_entity, empty_block_entity, data_limit, nbt.*} 这四类 lang 键变成只生成、不消费的死键（在库内 AgeratumLanguageProvider 里仍有）。

为什么这不只是“精简提示”：右键打开原生 GUI 的前提是 getBlockState(pos).getMenuProvider(...) 或 BE 实现 MenuProvider，没有 GUI 的方块实体（大量机器方块）在 140 里还能查到 NBT 配置，在 142 里彻底无法查看——而 unavailableMenu 只给出 tooltip.ageratum.structure_preview.no_gui（“No preview available”），没有任何替代路径。PR 描述只写了“同步简短悬停提示”，未提这一项。

建议：确认是否有意砍掉；若有意，请在描述里写清“无菜单方块不再提供 NBT 详情”，并顺手清理上述死键与 describe()；若属误删，需要库侧补回（在 no_gui 分支里至少回退到旧的 NBT 文本）。

💡 建议（不阻塞）

1. inspect 提示丢了操作说明：由 "Left-click a block to inspect it; drag to pan, right-drag to rotate" 改为 "Click to inspect"。但 1.21.1 上原生 GUI 浮窗是右键触发（mouseReleased 的 button == 1 分支），新文案完全没有提示右键能力，用户只能靠“点了没反应 + No preview available”自行摸索。建议改成类似“左键查看方块 / 右键打开界面”。
2. StructureDetailsPager 变成死类：140 里它是详情分页器，142 改用 selectedBlockTooltip 列表后已无引用（源码文件未删）。库侧可清理。
3. StructureGuiRenderStateMixin 在 setupRenderState TAIL 无条件 RenderSystem.enableBlend()：仅在 isRendering() && opacity < 1 时生效，退出 renderOnly 后不会 disableBlend。原版每种 RenderType 各自设置混合态，通常无残留问题，但建议在 StructureGuiPreview.render 的 finally 里恢复混合状态，避免与其它在浮窗之上绘制的图层相互影响。此条属库内部实现，非本 PR 缺陷，供后续跟进。
4. 描述里的“菜单与配方书状态隔离”已在库侧落实：StructureGuiSession.create 保存并恢复 minecraft.player.containerMenu（finally 块）、StructureGuiRecipeBookMixin 在渲染期强制 isVisibleAccordingToBookData = false、StructureGuiPreview.clear() 注释明确“从不调用 onClose/removed 生命周期”。这张声称可以判 ✅，但建议作者在描述里补一句“预览不执行任何容器交互/发包”，便于后续排查。

描述声称对照

描述声称	核对结果	判定
将 1.21.1 的藿香依赖更新至 0.0.1+build.142	libs.versions.toml:6；制品在 Maven 真实存在	✅
接入原生只读方块界面浮窗	库侧新增 StructureGuiSession/Preview/Geometry + GuideScreen 6 处接线；本体 0 行（不需要）	✅
同步简短悬停提示	inspect 文案确实变短；但同时删掉了 BE NBT 详情，见 ⚠️	⚠️ 部分成立
空玩家背包	假 Player 的 inventory 为新建空背包，createMenu(0, inv, player) 传入	✅
物品淡出动画	StructureGuiSession.opacity/tint + StructureGuiRenderStateMixin/StructureGuiGraphicsMixin 双层着色	✅（仅静态推导）
菜单与配方书状态隔离	containerMenu 保存/恢复 + 配方书可见性屏蔽 + 不调用交互生命周期	✅

回归测试建议

1. 深色主题下打开手册结构预览：导出按钮应显示深色贴图（dark/guide/button_import.png），悬停出现下半帧高亮 —— 顺带确认本条与 26.1 的表现差异。
2. 右键一个有 GUI 的方块（如珠宝工作台 / 结构扫描仪）：浮窗应弹出原生界面、可拖动、右键关闭，且不向服务端发包、不改动玩家真实背包与配方书状态。
3. 右键一个没有 GUI 的方块：应显示 “No preview available”，不崩溃（unavailableMenu 路径）。
4. 左键点方块：inspect 提示正常；同时确认原先能看到的方块实体 NBT 行已消失（这是 ⚠️ 的现场确认）。
5. 浮窗开启时缩放手册 / 切换页面 / 关闭手册：removed() 会 clear() 会话，无残留渲染与状态泄漏；物品图标淡入淡出期间不出现“半透明未混合”的硬边（RenderStateShard 混合补丁的实际观感）。

[PigeonNian]

LGTM