[WhereisFff]

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

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

验证：:anvillib-rendering-neoforge-26.2: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 #288 已合并（squash c0e0d4c8 之后的 dev/26.2，合并树与 head ce0aacc7 完全一致，2026-11-14T18:43:36Z）。26.2 的 6 处注入逐一用未混淆 client.jar 核对通过；其中两处 @ModifyArgs 已正确跟上 26.2 的关键 API 漂移——规范构造器改取 Matrix3x2fc（接口）而非 Matrix3x2f，且 PictureInPictureRenderer 构造器变成无参、textureView 走既有 AT 放宽——三处都对上了。需要跟进的是「光照设置在空 level 早退之前执行且不再恢复」「PiP 内复用真实相机剔除实体」「getSeaLevel() 与 1.21.x 线不一致」三点。

一、合并态与范围

判据	结果
state / merged / merged_at	closed / true / 2026-11-14T18:43:36Z
base / 合并树 vs head	dev/26.2 / 空 diff ⇒ 进主干的就是 ce0aacc7
规模	34 文件 +3295/−0，与收到的 diff 一致
head CI	build / build ✅
既有评论	仅 Roseau API 报告
语言文件	en_us / en_ud / zh_cn 各 107 条 ✅

二、注入点与 PiP API 逐条核实（26.2 未混淆 jar）

注入 / 依赖	核对结果
innerBlit(RenderPipeline, GpuTextureView, GpuSampler, IIII, FFFF, I) ordinal=4	类里两个重载（Identifier 版 code=46、GpuTextureView+GpuSampler 版 code=57），mixin 用完整描述符锁定后者 ✅；ordinal=4 = 第 5 个 int = color ✅
innerFill(…, IIIII, Integer) 两个 handler	单重载（code=59）⇒ ordinal=4 = color ✅；尾部 Integer handler 匹配渐变参数 ✅
innerTiledBlit(…, IIIIII, FFFF, I) ordinal=6	code=61；7 个 int（6 坐标 + color）⇒ ordinal=6 = 第 7 个 = color ✅
text(Font, FormattedCharSequence, IIIZ) ordinal=2	text 有 4 个重载（String/Component × III/IIIZ 形态），mixin 按描述符锁定 IIIZ（code=53）✅；ordinal=2 = 第 3 个 int = color ✅
Screen.extractBackground(GuiGraphicsExtractor, int, int, float)	public code=56 ✅
RecipeBookComponent.isVisibleAccordingToBookData()Z	private code=15 ✅
BlitRenderState.<init> 14 参 + args.set(11, …)	该类有两个构造器：13 参 Matrix3x2f 版与 14 参 Matrix3x2fc 版；mixin 精确指向后者 ✅。字节码显示 GuiRenderer.submitBlitFromItemAtlas 与 PictureInPictureRenderer.blitTexture 各自只调用一次该 14 参构造器 ⇒ 命中唯一，index 11 = int color ✅
PictureInPictureRenderer 无参构造器	26.2 改为 ()V public（26.1 是 (MultiBufferSource$BufferSource)）⇒ StructureRenderEvents.register(State.class, StructurePreviewPipRenderer::new) 与「类里不写构造器」一致 ✅
renderToTexture(T, PoseStack, SubmitNodeCollector)	基类 abstract ✅，签名与 override 一致；blitTexture(T, GuiRenderState) protected code=73 ✅
this.textureView 访问	字段在 jar 里是 private，由既有（base 上就有，第 24 行）module.rendering/.../accesstransformer.cfg 的 public … PictureInPictureRenderer textureView 放宽 ⇒ 合法 ✅

三、需要跟进（合并后）

• 光照设置发生在空 level 早退之前，且不再恢复：renderToTexture 首行就是 mc.gameRenderer.lighting().setupFor(Lighting.Entry.LEVEL)，随后才 if (mc.level == null) return;——即「什么都没画却已改掉全局光照入口」；而 1.21.x / 26.1 版本会保存并恢复 RenderSystem.setShaderLights(previousLights)，26.2 版完全没有恢复动作。若 26.2 的 feature 渲染并非在提交几何时烘焙光照，这段会把 Lighting.Entry.LEVEL 的平行光状态泄漏给同帧后续的 GUI/世界绘制。建议：把 setupFor 移到 null 检查之后，并在 finally 中恢复（或注释说明 26.2 为何无需恢复）。
• PiP 内复用真实世界相机剔除实体（与 1.21.8 / 1.21.11 / 26.1 同源）：gameRenderer.gameRenderState().levelRenderState.cameraRenderState 被传给 entityRenderDispatcher.submit(...) 与 blockEntityRenderer.submit(...)，实体裁剪距离、shouldRender、阴影判定都按玩家真实视角算 ⇒ 结构里位于玩家背后或超视距的实体不出现在预览窗。建议构造与预览 state.transform() 对齐的相机状态。
• 跨线海平面不一致（已实测）：本线 getSeaLevel() 返回 0，而 dev/1.21.8 上的同文件返回 63（26.1 也是 0）；getBlockTint(...) 恒 -1、cardinalLighting() 恒 CardinalLighting.DEFAULT。渲染走 ProjectionScene(mc.level) 暂时绕开了它，但任何以后直接把沙盒当 BlockAndTintGetter 用的扩展会拿到「无生物群系染色 + 默认朝向光照 + 海平面 0」。
• 对既有 AT 的硬依赖需要写明：Effects.render 把 GpuTextureView 交给调用方，其取用依赖 accesstransformer.cfg 第 24 行放宽的 PictureInPictureRenderer.textureView。该行不在本 PR 范围内（base 已有），但只要它被清理或上游改字段名，本模块立刻编译失败——建议在该 AT 行与 blitTexture override 各留一句用途注释。
• defaultRequire: 1 + required: true 下 pin 死 record 构造器没有运行时保险：两个 @ModifyArgs 精确绑定 14 参构造器，而 build / previewTest 不加载 mixin，CI 绿不证明命中（本次由字节码手工证）。这一族的风险已被本 PR 自己证明是真实的——26.1→26.2 就把构造器的 Matrix3x2f 换成了 Matrix3x2fc，照抄上一线就会静默失配。建议对这两个纯视觉注入加 require = 0。
• createClientClockManager 在注册表缺席时静默无时钟（同 26.1）：registryAccess.lookup(Registries.WORLD_CLOCK) 为空时 clockManager 无任何时钟数据、无日志；依赖 clockManager() 的渲染会拿到空/默认值。建议补一条一次性 warn。
• 每帧新建三个渲染器对象：new ProjectionScene(...)、new ModelBlockRenderer(...)、new FluidRenderer(...) 每帧一次，建议提到字段（ambientOcclusion 变更时重建）。
• 混合层流体对 ChunkSectionLayer.values() 逐个提交 3 次：每次 submitCustomGeometry 只让一个层收到顶点，另两次为空缓冲；可改成只按 fluidModels.get(fluid).layer() 提交一次，减少无效几何缓冲。
• mixins.json 的 compatibilityLevel 本线也是 JAVA_8（1.21.1 / 1.21.4 / 1.21.8 为 JAVA_21）——既有配置，新增 6 个 mixin 后建议跨线统一。
• 既有项（跨线通病）：getFilledBlocks() 返回复用的 MutableBlockPos；StructureGuiProviders.register 冲突直接抛 IllegalStateException（客户端初始化期）；StructureBlockEntityDetails.describe / StructureDetailsPager 仍无生产调用方（107×3 条 lang 随之闲置）。

四、与 26.1 的差异对照（26.2 适配点，均已核实）

维度	26.1	26.2（本 PR）
BlitRenderState 规范构造器	Matrix3x2f	Matrix3x2fc（接口）⇒ 描述符必须同步，作者已改对 ✅
PiP 构造器	(MultiBufferSource$BufferSource)	无参 ()V ✅
纹理提交	collector 由方法参数传入	同（renderToTexture(T, PoseStack, SubmitNodeCollector)）
覆盖效果入口	Effects.render(State)	Effects.render(State, GpuTextureView, GuiRenderState)，在 blitTexture 里 super 之后调用 ✅ 与 README「26.2/26.3 收到已完成纹理」一致
光照	RenderSystem.getShaderLights() 保存/恢复	gameRenderer.lighting().setupFor(...)，无恢复
实体加载	EntityType.loadEntityRecursive(data, level, EntitySpawnReason.STRUCTURE, …)	new EntitySpawnRequest(EntitySpawnReason.STRUCTURE, true) ✅
chunk/pos 工具	ChunkPos.asLong/pack	ChunkPos.pack/containing ✅
表面选择	Sheets.translucentBlockSheet()/cutoutBlockSheet()	Sheets.translucentBlockItemSheet()/cutoutBlockItemSheet() ✅
语言 / mixin 配置	107 × 3 / JAVA_8	同 ✅

五、验证边界

未执行 Gradle 构建、runClient 与游戏内实测（PR 自述「客户端画面尚未实测」）；previewTest 只覆盖 provider 注册、renderOnly 嵌套/异常恢复与缓动函数，不加载 mixin、不渲染。本文结论来自静态读码 + 26.2 未混淆 client.jar 的方法表与字节码（上表逐项给出描述符/code=/构造器调用唯一性）、accesstransformer.cfg 逐行核对（确认 textureView 的放宽在 base 上已存在）+ 合并树/head 对账 + head CI + 三份 lang 键数比对 + 1.21.8 线的 getSeaLevel() 实测对照。建议实机补测：真实容器屏在不同 GUI scale 下的浮窗裁剪与层级、F3 隐藏 GUI、结构内实体位于玩家背后/远处的可见性（第三节第二条）、大尺寸物品淡出、时钟/时间相关渲染，以及同一结构在 26.1 与 26.2 上的观感一致性（光照与海平面两处差异最可能表现为「版本间看起来不一样」）。