ReadStar

模组

· 作者 FrozenStream

一个模组,添加了可配置且更逼真的星空效果。

0 本站下载 0 关注 更新于 4 个月前

最新 0.3.7_beta_neoforge_mc1.21.1 · 1.21.1 · NeoForge

一键开服(送7天)

ReadStar — NeoForge 天文模组

Night

一款由真实天体力学和星表数据驱动的 Minecraft 天空模组,具备行星轨道系统、星表、视场感知渲染以及服务器同步的天体配置功能。

作者: FrozenStream

特性

  • 真实星表 — 来自 Gaia DR3(颜色)+ BSC5(亮星后备)的 12,000+ 颗真实恒星,每颗星拥有独立的光度和辉光
  • 真实天体力学 — 开普勒轨道系统,支持无限嵌套深度
  • 大气散射 — 基于 HSV 的大气颜色与辉光计算,包含全天空叠加层和恒星晕圈
  • 彗星渲染 — 贝塞尔曲线尘埃尾 + 离子双尾结构,带有动态抖动效果
  • 视场感知渲染 — 自定义着色器确保在 FOV 变化时恒星屏幕尺寸保持恒定
  • 零代码自定义 — 只需放置 PNG 图片,即可为任何天体添加 8 个月相
  • 服务器同步 — 天体配置在服务端管理,自动同步至所有客户端

快速开始

./gradlew build          # 构建
./gradlew runClient      # 运行客户端
./gradlew runData        # 数据生成(图集配置)
./gradlew runServer      # 运行服务端

天体系统通过 data/readstar/celestial/system.json 处的 数据包 定义,星表则通过 assets/readstar/custom/stars/stars.json 处的 资源包 定义。

配置文件更改按 F3+T 生效。数据包更改需要执行 /reload 或重启。


配置

配置文件:run/config/readstar-common.toml

选项 默认值 描述
starCoreSize 0.648 恒星核心四边形大小乘数
starGlowSize 1.5 亮星辉光四边形大小乘数
starFovCompensationStrength 0.8 恒星 尺寸 的 FOV 补偿强度。1.0 = 完全补偿,0.0 = 无补偿
starFovBrightnessStrength 1.0 放大时的恒星 亮度 增强。0.0 = 无增强
celestialApparentSizeFactor 4000.0 天体视大小因子
celestialApparentSizeMin 1.024 最小视大小限制

视场感知渲染

恒星使用自定义着色器,将每个点分离为 位置 和 偏移量:

属性 含义 行为
Position (vec3) 天球坐标,4个顶点共享 经 MVP 变换,自然受 FOV 影响
Offset (vec3) 广告牌角点偏移量,每个顶点唯一 乘以 FovCompensation 以进行尺寸校正

公式:FovCompensation = tan(fov/2) / tan(35°) × strength + (1 - strength)

着色器逻辑:worldPos = Position + Offset × FovCompensation

单星亮度

基于 Vmag(视星等),具有独立的衰减阈值:

参数 公式 备注
Alpha clamp(1 - max(0, Vmag-3)/12, 0.4, 1) Vmag ≤ 3 时全亮度
RGB clamp(1 - max(0, Vmag-1)/19, 0.7, 1) Vmag ≤ 1 时全亮度
Size clamp(1 - Vmag/12, 0.5, 1) × starCoreSize Vmag 越大,点越小

仅当 Vmag < 2.0 时生成辉光四边形:< 0.5 → 高 / < 1.5 → 中 / < 2.0 → 低。


数据包 — 天体系统

路径: data/readstar/celestial/system.json

放置在 saves/<world>/datapacks/<pack>/data/readstar/celestial/system.json 或服务端的 world/datapacks/ 中。

结构

{
  "System": {
    "<name>": {
      "mass": <double>,
      "radius": <double>,
      "luminance": <int>,
      "unstableDirtySnowball": <bool>,
      "hasAtmosphere": <bool>,
      "atmosphereHSV": <int>,
      "starHSV": <int>,
      "axis": [<x>, <y>, <z>],
      "orbit": {
        "semiMajorAxis": <double>,
        "eccentricity": <double>,
        "inclination": <double>,
        "argumentOfPeriapsis": <double>,
        "longitudeOfAscendingNode": <double>,
        "initialMeanAnomaly": <double>
      },
      "children": { "<name>": { ... } }
    }
  }
}

字段参考

字段 描述
mass 质量(kg)。0 表示固定在父级位置
radius 半径(m)。视大小 = max(1.024, radius / distance × factor)
luminance 自发光度 0~15。>0 表示恒星;子代自动向上解析 hostStar
unstableDirtySnowball 彗星标志。true 渲染双尾结构
hasAtmosphere 是否有大气层(控制叠加层和辉光渲染)
atmosphereHSV 大气层 HSV 颜色,打包整数 (H<<16 | S<<8 | V)。H=色调, S=饱和度, V=密度 (0~255)
starHSV 天体自身颜色,编码方式相同。发光体 = 发射,非发光体 = 表面反射
axis 旋转轴。零向量默认为 (0,0,-1)
orbit.semiMajorAxis 半长轴(m)。0 表示无轨道
orbit.eccentricity 偏心率。0 表示圆形
orbit.inclination 轨道倾角(弧度)
orbit.argumentOfPeriapsis 近心点幅角(弧度)
orbit.longitudeOfAscendingNode 升交点经度(弧度)
orbit.initialMeanAnomaly 初始平近点角(弧度)

名称不区分大小写。children: {} 表示无子代。嵌套深度不限。

完整示例

太阳 → 地球 + 火星 → 月球。真实的太阳系数据。

{
  "System": {
    "Sun": {
      "mass": 1.989e30, "radius": 6.957e8, "luminance": 15,
      "unstableDirtySnowball": false, "hasAtmosphere": false, "atmosphereHSV": 0, "starHSV": 2172671,
      "axis": [0, 0, 0],
      "orbit": { "semiMajorAxis": 0, "eccentricity": 0, "inclination": 0, "argumentOfPeriapsis": 0, "longitudeOfAscendingNode": 0, "initialMeanAnomaly": 0 },
      "children": {
        "Earth": {
          "mass": 5.972e24, "radius": 6.371e6, "luminance": 0,
          "unstableDirtySnowball": false, "hasAtmosphere": true, "atmosphereHSV": 9738751, "starHSV": 9732275,
          "axis": [0, 0, 0],
          "orbit": { "semiMajorAxis": 1.496e11, "eccentricity": 0.0167, "inclination": 0, "argumentOfPeriapsis": 1.796, "longitudeOfAscendingNode": 0, "initialMeanAnomaly": 6.240 },
          "children": {
            "Moon": {
              "mass": 7.342e22, "radius": 1.737e6, "luminance": 0,
              "unstableDirtySnowball": false, "hasAtmosphere": false, "atmosphereHSV": 0, "starHSV": 1707468,
              "axis": [0, 0, 0.5],
              "orbit": { "semiMajorAxis": 3.844e8, "eccentricity": 0.0549, "inclination": 0.0899, "argumentOfPeriapsis": 0, "longitudeOfAscendingNode": 0, "initialMeanAnomaly": 0 },
              "children": {}
            }
          }
        },
        "Mars": {
          "mass": 6.417e23, "radius": 3.390e6, "luminance": 0,
          "unstableDirtySnowball": false, "hasAtmosphere": true, "atmosphereHSV": 1336835, "starHSV": 1356697,
          "axis": [0, 0, 0],
          "orbit": { "semiMajorAxis": 2.279e11, "eccentricity": 0.0934, "inclination": 0.0323, "argumentOfPeriapsis": 0, "longitudeOfAscendingNode": 0.865, "initialMeanAnomaly": 0 },
          "children": {}
        }
      }
    }
  }
}

继承与时间

  • hostStar:递归向上解析至最近的 luminance > 0 祖先
  • 位置 = parent.position + orbit(parent.mass, gameTime)
  • 根节点固定在 (0, 0, 0)
  • gameTime 驱动轨道运动;daylightTime(0~24000)驱动旋转/天顶
  • 月相根据观测者-卫星-恒星的几何关系自动计算

大气系统

每个天体可以定义大气颜色(HSV)和自身颜色(HSV),两者均以打包整数表示:

atmosphereHSV / starHSV = (H << 16) | (S << 8) | V
组件 位宽 范围 含义
H (色调 Hue) 16-23 0~255 色调 (0=红色 → 255 循环回红色)
S (饱和度 Saturation) 8-15 0~255 饱和度 (0=灰色,255=纯色)
V (明度 Value) 0-7 0~255 密度/亮度 (atmosphereHSV=密度,starHSV=亮度)

示例值:

天体 atmosphereHSV starHSV 备注
Sun 0 2172671 无大气层,G型黄白色恒星
Earth 9738751 9732275 蓝色天空 (H=0.58, S=0.6, V=1.0)
Mars 1336835 1356697 微弱的红褐色 (V=0.01,非常稀薄)

通过 CelestialBody.packHSV(h, s, v) 进行打包/解包,以及 getHueFloat/getSaturationFloat/getValueFloat 获取浮点值。

发光计算 (computeGlowColor):光晕颜色 = 星光 × 大气散射。色调向大气颜色偏移;饱和度和亮度略微提升。

渲染层级:

1. renderSkyDisc       → 原版生物群系天空背景
2. Bodies + stars      → 发光/非发光天体 + 星表
3. renderAtmosphereOverlay → 半透明全天空大气层(夜间逐渐消失)

天体纹理

天体纹理按类别组织,由 celestial.json 图集自动发现:

assets/<namespace>/textures/environment/celestial/
├── luminous/<name>.png       # 发光天体(单张图像,无月相变化)
├── non-luminous/<name>/      # 非发光天体(8张月相 PNG)
└── halo.png                  # 光晕纹理(灰度径向衰减)

发光天体需要在 luminous/ 中放置一张 PNG。非发光天体需要在 non-luminous/<name>/ 中放置 8 张月相 PNG。readstar:luminous/white_sun.png 是占位符——请替换为您自己的文件。


资源包

星表

路径:assets/readstar/custom/stars/stars.json

数据源

星表由 .data/ 中的脚本自动生成:

脚本 来源 输出
generate_stars.py BSC5 亮星星表 stars_named.json(361 个 IAU 命名星)+ stars_numbered.json(8043 个 HR 编号星)
gaia_download.py Gaia Archive TAP API gaia_bright_with_teff.vot(包含有效温度)
gaia_to_stars.py Gaia DR3 + BSC5 回退 stars_gaia_named.json(361 个)+ stars_gaia_numbered.json(11809 个)

颜色处理流程:优先使用 Gaia GSP-Phot 有效温度 → 普朗克黑体辐射 → sRGB;回退方案为使用 bp_rp 色指数映射。最亮的 12 颗恒星(天狼星、织女星等)由于 Gaia 探测器饱和,保留 BSC5 数据。

JSON 格式

{
  "Stars": [
    {
      "name": "Sirius",
      "position": [-0.1875, -0.2876, 0.9392],
      "Vmag": -1.46,
      "color": 4294967295
    }
  ]
}
字段 描述
name 标识符(保留字段,无运行时效果)
position 单位球方向 [x,y,z],归一化至距离 100。Y=北天极
Vmag 视星等(Gaia G 波段或 BSC5 V 波段)。决定发光等级和亮度衰减
color ARGB 颜色值;用于图集精灵生成的键

自定义月球纹理

核心功能:只需放置 PNG 文件,即可为任何天体添加 8 个月相——零代码。

目录结构

assets/<namespace>/textures/environment/celestial/non-luminous/<body-name>/
  • <body-name> 必须与 system.json 中的名称完全一致(小写)
  • 需要恰好 8 张 PNG,文件名固定:
文件 阶段
full_moon.png 满月
waning_gibbous.png 亏凸月
third_quarter.png 下弦月
waning_crescent.png 残月
new_moon.png 新月
waxing_crescent.png 蛾眉月
first_quarter.png 上弦月
waxing_gibbous.png 盈凸月

要求

规范 值
格式 PNG,32位 RGBA
尺寸 推荐 16×16 或 32×32
边缘 透明 (alpha=0)
颜色 自着色;无运行时着色

示例:木星

assets/readstar/textures/environment/celestial/non-luminous/jupiter/
├── full_moon.png
├── waning_gibbous.png
├── third_quarter.png
├── waning_crescent.png
├── new_moon.png
├── waxing_crescent.png
├── first_quarter.png
└── waxing_gibbous.png

同时在 system.json 中定义木星的轨道(见上文示例)。

工作原理

  1. textures/environment/celestial/ 下的 PNG 由 Minecraft 的图集系统自动发现
  2. ReadstarSkyRenderer 扫描 moons/ 子目录并按组构建 GPU 缓冲区
  3. 通过 body.name 进行运行时匹配

其他模组可通过资源包优先级覆盖纹理。


精灵与图集

恒星图集

assets/readstar/atlases/star.json 声明了 readstar:star 源。在运行时,来自 stars.json 的所有 color 值会逐像素对基础模板进行着色:

模板 路径 用途
star_base.png textures/environment/star/ 核心 (32×32 RGBA)
star_glow_low.png 同上 低亮度辉光
star_glow_med.png 同上 中等亮度辉光
star_glow_high.png 同上 高亮度辉光

每种颜色对应 4 个精灵:color_{c}、glow_low_{c}、glow_med_{c}、glow_high_{c}。

要求:32位 RGBA,32×32,黑色边缘,辉光亮度抑制为 ×0.35。

天体图集

assets/readstar/atlases/celestial.json 使用 minecraft:directory 源,自动扫描 textures/environment/celestial/ 下的所有命名空间。


网络同步

服务器加载 data/readstar/celestial/*.json 并通过 readstar:planet_system 数据包进行广播。客户端在 CelestialBodyManager.initializeFromJson() 中重建天体树。


构建与故障排除

./gradlew build          # 构建 JAR
./gradlew runData        # 数据生成(图集配置)
./gradlew runClient      # 运行客户端
./gradlew runServer      # 运行服务器

输出:build/libs/readstar-*.jar

症状 检查项
紫色/黑色恒星纹理 star_base.png 是否为 32位 RGBA?
紫色月相 缺少 PNG 文件或文件名不匹配
天体不可见 是否具有 hostStar(祖先发光度 > 0)?
辉光/光环未渲染 halo.png 是否位于 textures/environment/celestial/ 下?
大气层颜色错误 atmosphereHSV / starHSV 是否正确打包?
数据包未应用 执行 /reload 或重启
资源包未更新 按 F3+T
FOV 补偿无效 starFovCompensationStrength 是否 > 0?

© 2026 FrozenStream. Licensed under MIT.

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源