Astrophysics - 引力透镜与黑洞渲染

Astrophysics 是 Minecraft 1.12.2 的 CRL-only 客户端渲染模组：服务端依据方块注册名、TileEntity ID 和 NBT 子集匹配规则，同步经过验证的透镜/黑洞视觉描述；客户端按玩家 Render Distance 与 FOV 裁剪并渲染引力透镜。

运行要求与范围

• 仅支持 Java 25、Cleanroom 0.6.8-alpha+ 和 CraftTweaker 4.1.20.711；传统 Forge、更旧 Cleanroom 与其他 Java feature version 均会 fail fast。CraftTweaker 是硬依赖。
• 以 OptiFine 1.12.2_HD_U_G6_pre1 且未启用 shaderpack 为验收基线。
• 渲染开发另设隔离的 Actinium 实验基线：只使用权威远端与本地一致的 main@0e246eefa000f9b95355bb1697e1ea1247c01bed 及其主分支 JAR；其他 branch artifact 不进入 fixture 或支持声明。客户端 fixture 使用 Cleanroom 0.6.8-alpha 所需的 Fugue/Scalar，并排除 OptiFine。该精确 Actinium artifact 与迁移前 Astrophysics artifact 已通过 0.6.8 的启动/GL/FML smoke；当前 Java 25 major-69 候选仍须重新执行同一门槛，且既有 smoke 从未证明进入世界后的 Lens/C512 或 active shaderpack 行为。
• 当前仍不支持 active shaderpack。冻结 Actinium 源码表明其 RenderWorldLastEvent 位于 Actinium final 之后，且 final 会恢复共享深度的 Minecraft 主 framebuffer；这只是待真实 world-render gate 验证的 revision-specific implementation contract，不能替代运行时证据。使用正式透镜效果前仍须关闭 shaderpack。
• Sample Steps 和 Raymarch Iterations 的有效范围均为 1..64；单体预设中传 0 会继承全局值。

构建与依赖契约

• 本项目使用 Gradle 9.6.1 Wrapper 与 Unimined 1.4.27-kappa；Minecraft 开发环境固定为 MCP stable 39 / Cleanroom 0.6.8-alpha。Wrapper bootstrap、Gradle daemon 与项目 toolchain 均要求 Java 25，Foojay Resolver 只用于 provision Adoptium Java 25；解析失败时直接失败，不回退到其他 Java 版本。
• 所有仓库自有 Java source set（main、test、runtime probe、dedicated-server test）统一以 --release 25 编译；正式 remapped Astrophysics JAR 与独立 runtime probe 的每个 class 均由构建检查强制为 major 69。仓库不保留 RFG、Forge 2847 开发基线、Java 8 toolchain 或 major 52 产物路径。
• 产品 metadata 明确要求 FML cleanroom@[0.6.8-alpha,)；当前可复现发布集成 fixture 为 Cleanroom 0.6.8-alpha / Forge 14.23.5.2864。版本范围表达可接受下限，不把未经实际 fixture 验证的更高 Cleanroom 版本描述为已通过。
• CraftTweaker 的 Maven 分拆解析版本及目标 fat JAR 包版本均为 1.12-4.1.20.711，只用于编译、测试和开发运行时，不会打入 Astrophysics 正式 JAR。目标 CRL 的 FML container 对 crafttweaker 实际声明的精确版本是 4.1.20；Astrophysics 的运行时精确依赖和发布专服启动门约束该 container 版本，而不是 Maven/fat JAR 包版本。目标 fat JAR 与 Maven Main JAR 不等价，每个候选发布物仍须通过该门，并确认正式 Astrophysics JAR 不含 CraftTweaker 或 JUnit 类。

ZenScript API

入口类为 mods.astrophysics.Lenses：

• setGlobalRenderControls(sampleSteps, raymarchIterations, warpStrengthMultiplier)
• registerLensPreset(id, schwarzschildRadius, influenceRadius, deflectionStrength, alpha, expression, sampleSteps, raymarchIterations, warpStrengthMultiplier)
• registerBlackHolePreset(...)：在普通预设参数后追加吸积盘 ARGB 颜色/纹理、内外半径、Doppler Beaming、Photon Ring Brightness 和 Fog/Atmo Mix。
• setBlackHoleRendererDefault(presetId)：选择一个已注册的黑洞预设，作为专用黑洞渲染器方块新 TileEntity 的默认参数。
• addBlockRule(block, tileEntityId, nbtSubset, presetId, cameraOffsetX, cameraOffsetY, cameraOffsetZ)

半径以方块为单位，最多两位小数；相机位置为方块中心加 cameraOffset。函数表达式会在服务端加载期预采样为 256 个点，客户端不会执行 ZenScript。

表达式可使用变量 r、rs、ri、strength、alpha，运算符 + - * / ^ 与括号，以及 abs(x)、min(a,b)、max(a,b)、clamp(x,min,max)、sin(x)、cos(x)、exp(x)、log(x)、sqrt(x)。表达式必须在全部采样点产生有限值。

最小有效 scripts/gravitational_lens.zs：

mods.astrophysics.Lenses.setGlobalRenderControls(24, 64, 1.0);

mods.astrophysics.Lenses.registerLensPreset(
    "example.beacon_lens", 1.00, 8.00, 1.25, 0.80,
    "clamp((1-r) * strength * alpha, 0, 1)",
    0, 0, -1.0
);

mods.astrophysics.Lenses.addBlockRule(
    <minecraft:beacon>, "", null, "example.beacon_lens", 0.0, 0.0, 0.0
);

mods.astrophysics.Lenses.registerBlackHolePreset(
    "example.renderer_black_hole", 1.00, 16.00, 1.50, 0.90,
    "clamp((1-r) * strength * alpha, 0, 1)",
    0xFFFFA040, "", 1.50, 6.00, 1.00, 1.50, 0.25,
    32, 64, 1.25
);
mods.astrophysics.Lenses.setBlackHoleRendererDefault("example.renderer_black_hole");

setBlackHoleRendererDefault 只能引用已通过 registerBlackHolePreset 注册的预设；普通透镜预设会在脚本加载期立即报错。设置后，新放置的 astrophysics:black_hole_renderer 使用该预设的透镜参数、256 点曲线、黑洞外观和已解析的渲染控制；相机偏移默认保持 0.0, 0.0, 0.0。未设置时，方块继续使用内置默认值。该选择与其他脚本配置一样会在 post-init 后冻结。

许可证与声明

Copyright (C) 2026 Que-Eng。

Astrophysics 的完整源代码及其分发产物以 GNU General Public License version 3 only（GPL-3.0-only）发布。完整许可证文本见根目录的 LICENSE；分发、第三方参考和派生使用说明见 NOTICE。构建出的正式 JAR 在 META-INF/LICENSE 与 META-INF/NOTICE 中随附两份文件。

gravitational_lens.fsh 于 2026-07-15 依据 baopinshui/NPGS commit c45907c45dbfa55e7b407dedf14f5a15233f6978 中的 NPGS/Sources/Engine/Shaders/BlackHole.frag.glsl 改编。改编保留了光学贡献累积、单次背景取样和 tone mapping 的结构思路，并替换为 Minecraft scene color/depth capture、统一 RGBA16 optical atlas、exact/dense 累积、动态 photon-shell 能量与 GLSL 1.20 集成。NPGS 以 GPL-3.0 发布且不是 Astrophysics 的运行时依赖；上游版权归原作者和贡献者所有，精确声明见 NOTICE。链接的 ShaderToy 作品仅作视觉参考，本项目未采用其源码、shader、资源或二进制材料。