[WhereisFff]

将结构渲染、隔离沙盒、相机拾取和只读 GUI 浮窗移入砧库，让手册与机器界面共用实现，避免机器功能依赖手册模组。

• 提供特殊方块 GUI 注册、减少动态效果参数及附加模型和后处理接口
• 适配 1.21.8 的原生渲染与透明度补丁，保留结构中的方块实体和实体
• 提供通用翻译、接口说明和只读作用域回归检查

验证：:anvillib-rendering-neoforge-1.21.8:build（含 previewTest）与 git diff --check 通过；已对照当前版本源码核查 Mixin 目标。客户端画面尚未实测。

[Gugle2308]

🌿 Roseau API Breaking Change Report

Module	Status	Breaking Changes
codec	✅ Compatible	0
collision	✅ Compatible	0
cube	✅ Compatible	0
config	✅ Compatible	0
integration	✅ Compatible	0
moveable-entity-block	✅ Compatible	0
network	✅ Compatible	0
rendering	✅ Compatible	0
space-select	✅ Compatible	0
font	✅ Compatible	0
util	✅ Compatible	0
explosion	✅ Compatible	0
rpc	✅ Compatible	0
math	✅ Compatible	0
multiblock	✅ Compatible	0
recipe	✅ Compatible	0
registrum	✅ Compatible	0
sync	✅ Compatible	0
ui	✅ Compatible	0
wheel	✅ Compatible	0
main	✅ Compatible	0

Full CSVs: see the Artifacts section of this workflow run.

[Gugle2308]

结论：PR #285 已合并（squash bd25230c，dev/1.21.8 tip，合并树与 head 1d5287ee 完全一致，2026-11-14T18:43:25Z）。我逐条核对了 1.21.8 的 mixin 目标与字节码，6 个新注入点全部命中，且 args.set(11, …) 的颜色下标与 BlitRenderState 的 14 参构造器一致；需要跟进的是「按 record 规范构造器 pin 死的注入没有运行时保险」「方块几何用了 item sheet」以及两处跨线差异。

一、合并态与范围

判据	结果
state / merged / merged_at	closed / true / 2026-11-14T18:43:25Z
merge_commit_sha	bd25230c963fd3287bd24a8915a63ecc153338b2 = dev/1.21.8 tip
合并树 vs head	空 diff ⇒ 进主干的就是 1d5287ee
规模	35 文件 +3305/−1，与收到的 diff 完全对应（含 ProjectionScene.shifted 一处放宽为 public、mixins.json 增加 6 条、en_ud/en_us/zh_cn 各 109 键）
head CI	build / build ✅
既有评论	仅 Roseau API 报告

二、已核实的注入点（1.21.8 官方 client_mappings + 混淆 client.jar）

注入	核对结果
GuiGraphics.submitBlit(…,IIIIFFFFI) ordinal=4	方法 443:444，该类仅此一个 submitBlit；int 形参依次为 x0/y0/x1/y1/color，ordinal=4 = 第 5 个 int = color ✅
submitColoredRectangle 两个 handler	177:186，只有一个重载 (RenderPipeline, TextureSetup, int,int,int,int,int, Integer)；ordinal=4 = 第 5 个 int（color）✅，另一个 handler 接尾部 Integer（渐变）✅
drawString(Font, FormattedCharSequence, IIIZ) ordinal=2	222:226 存在；GuiGraphics 里 drawString 有 6 个重载，但本 mixin 用了完整描述符，不会误匹配 ✅
GuiRenderer.submitBlitFromItemAtlas + BlitRenderState.<init>	方法 437:450 存在；字节码显示该方法只用 gcs.<init>:(RenderPipeline,TextureSetup,Matrix3x2f,IIIIFFFFI,ScreenRectangle,ScreenRectangle)V（整类仅此 1 处构造）⇒ @ModifyArgs 命中唯一，且 index 11 正是 int color（字段序 pipeline/textureSetup/pose/x0,y0,x1,y1/u0,u1,v0,v1/color/两个矩形）✅
PictureInPictureRenderer.blitTexture / OversizedItemRenderState	blitTexture(PictureInPictureRenderState, GuiRenderState) 72:83 存在；OversizedItemRenderState 组件含 guiItemRenderState ✅；父类构造器 (MultiBufferSource$BufferSource) ✅
Screen.renderTransparentBackground / RecipeBookComponent.isVisibleAccordingToBookData	413:414 / 228:228 均存在 ✅
graphics.peekScissorStack()	不是 vanilla：它是 NeoForge 补丁新增的 patches/net/minecraft/client/gui/GuiGraphics.java.patch 里 public ScreenRectangle peekScissorStack()（内部 scissorStack.peek()）⇒ 编译合法，但建议在代码注释里注明来源
enableScissor(0,0,XSize,YSize) 在平移后调用	已反汇编确认 1.21.8 的 GuiGraphics.enableScissor(IIII) 会 new ScreenRectangle(x0,y0,x1-x0,y1-y0) 再 transform(pose) 后入栈 ⇒ 在 translate(x,y)+scale 之后调用确实等于裁到浮窗矩形，写法正确 ✅

三、需要跟进（合并后）

• 按 record 规范构造器 pin 死的注入没有任何运行时保险：StructureGuiItemRendererMixin / StructureGuiOversizedItemMixin 的 @ModifyArgs 把 BlitRenderState.<init> 的 14 参描述符整串写死，而 anvillib_rendering.mixins.json 是 "required": true + "injectors": {"defaultRequire": 1} ⇒ 上游一旦改用 13 参便捷构造器或增删字段，就是启动崩溃而不是降级。而 build / previewTest 不会应用 mixin，CI 绿不能证明命中（本次是我靠字节码手工证的）。建议给这两个纯视觉注入加 require = 0。
• 方块几何用了 item sheet：StructurePreviewPipRenderer 对方块模型用 Sheets.cutoutBlockSheet() / Sheets.translucentItemSheet()。item sheet 的 lighting/shader 参数与 block sheet 不同（前者按 GUI 光照走），PiP 里给方块几何用会出现明暗与预期不一致的风险；若 1.21.8 的 Sheets 没有对应的 translucent block sheet，请在注释里写明这是有意的取舍，否则改成 block 版本。
• StructureGuiItemStateMixin 的快照时机是隐式契约：opacity 在 GuiItemRenderState.<init>（提取阶段）快照，而提交/绘制在之后。当前唯一调用方在 StructureGuiPreview.render 的同一作用域内提取，所以成立；但 StructureGuiSession.renderOnly 是 public API，外部若在提取之后才进入作用域会静默得到 alpha=1。建议在 renderOnly javadoc 写明「必须在 GUI 元素提取阶段之前进入作用域」。
• StructureRenderEvents.fallingBlocks 是全局注册：RegisterRenderStateModifiersEvent 给 FallingBlockRenderer 装的 modifier 对所有 SandboxRenderLevel 里的下落方块生效（不只是预览窗口），并直接把 state.level 换成沙盒——下游若按 level 查区块/光照可能拿不到数据。目前只在沙盒内生效，影响面可控，但建议注释说明这是为预览服务的全局修正。
• 悬挂实体坐标键需要按 1.21.8 再确认：本线 StructureSandboxFactory.relocateEntityData 从 TileX/TileY/TileZ 改成了 block_pos 整型数组平移，而 1.21.1/1.21.4 仍是 TileX/Y/Z。请实机确认 1.21.8 的悬挂/拴绳实体确实写 block_pos；若仍写旧键，预览里的悬挂实体会停在原坐标（纯视觉，不崩）。
• SandboxRenderLevel.recipeAccess()/fuelValues() 委托 Minecraft.getInstance().level（Objects.requireNonNull）⇒ 客户端断开/资源重载期间若仍有预览，会 NPE；getSeaLevel() 硬编码 63 也建议注明。这两点与 1.21.4 版本同源。
• scissor 与父级裁剪的嵌套：ScissorStack.push 是否与栈顶求交决定嵌套行为，建议实机验证「手册页本身有 scissor 时浮窗是否被正确裁到页内」。

四、与 1.21.1 / 1.21.4 的跨线差异（值得作为后续对齐基准）

维度	1.21.1（#283，open）/ 1.21.4（#284，merged）	1.21.8（本 PR）
结构渲染	改 GUI 矩阵、setShaderFog/RenderSystem.clear、自带 PreviewLightmapAtlas	PiP 纹理目标（StructurePreviewPipRenderer 226 行）：不再触碰全局 fog/lightmap/深度 ⇒ 状态泄漏问题在 1.21.8 这线实际消失，可作为旧线修法的参考
透明度	1.21.1 改 GuiGraphics.setColor；1.21.4 改 全局 RenderSystem.setShaderColor	4 个具体提交入口（blit/填充/渐变/文本）+ 物品/大物品的 duck 接口快照 ⇒ 作用面最精确，且按描述符精确匹配（旧线按名字匹配）
沙盒	DelegatingServerLevelAccessor 796/800/864 行、getMinBuildHeight 等旧名	796 行，1.21.8 命名（getMinY/getMaxY、getListOrEmpty/compoundStream、EntitySpawnReason.STRUCTURE）
死代码	StructureBlockEntityDetails.describe / StructureDetailsPager / StructureGuiSession.tint 无生产调用方	同（tint 这次真的被 mixin 用了，不再是死代码 ✅；describe/StructureDetailsPager 仍无调用方，109×3 条 lang 也随之闲置）

五、验证边界

未执行 Gradle 构建、runClient 与游戏内实测（PR 自述「客户端画面尚未实测」）；previewTest 只覆盖 provider 注册、renderOnly 嵌套/异常恢复与缓动函数，不加载 mixin、不渲染。本文结论来自静态读码 + 1.21.8 官方 client_mappings/混淆 client.jar 的成员与字节码核对（上表逐项已注明方法与行号）+ NeoForge 1.21.8 分支的 GuiGraphics.java.patch（确认 peekScissorStack 来源）+ 合并树/head 对账 + head CI。建议实机补测：真实容器屏在 100%/150% GUI scale 下的浮窗裁剪与层级、F3 隐藏 GUI、带 scissor 的宿主页面、大尺寸物品（OversizedItemRenderState）的淡出、结构内悬挂实体与乘客位置、以及同一结构在 1.21.4 与 1.21.8 上的观感一致性（两条线实现路径不同，这是最可能出现「版本间看起来不一样」的地方）。