ReadStar — NeoForge 天文模组

一款由真实天体力学和星表数据驱动的 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 中定义木星的轨道(见上文示例)。
工作原理
textures/environment/celestial/ 下的 PNG 由 Minecraft 的图集系统自动发现
ReadstarSkyRenderer 扫描 moons/ 子目录并按组构建 GPU 缓冲区
- 通过
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.
ReadStar — NeoForge Astronomy Mod

A Minecraft sky mod driven by real celestial mechanics and star catalog data, featuring planetary orbital systems, star catalogs, FOV-aware rendering, and server-synchronized celestial configuration.
Author: FrozenStream
Features
- Real Star Catalog — 12,000+ real stars from Gaia DR3 (color) + BSC5 (bright star fallback), with per-star brightness and glow
- Real Celestial Mechanics — Keplerian orbital system with unlimited nesting depth
- Atmospheric Scattering — HSV-based atmosphere color & glow computation with full-sky overlay and stellar halo
- Comet Rendering — Bézier dust + ion dual-tail structure with dynamic wobble
- FOV-Aware Rendering — Custom shader keeps star screen size constant across FOV changes
- Zero-Code Customization — Add 8 moon phases to any body by simply placing PNGs
- Server Sync — Celestial config managed server-side, auto-synced to all clients
Quick Start
./gradlew build # Build
./gradlew runClient # Run client
./gradlew runData # Data generation (atlas config)
./gradlew runServer # Run server
The celestial system is defined via data pack at data/readstar/celestial/system.json, and the star catalog via resource pack at assets/readstar/custom/stars/stars.json.
Config changes take effect with F3+T. Data pack changes require /reload or restart.
Configuration
Config file: run/config/readstar-common.toml
| Option |
Default |
Description |
starCoreSize |
0.648 |
Star core quad size multiplier |
starGlowSize |
1.5 |
Bright star glow quad size multiplier |
starFovCompensationStrength |
0.8 |
Star size FOV compensation. 1.0 = full, 0.0 = none |
starFovBrightnessStrength |
1.0 |
Star brightness boost when zoomed in. 0.0 = none |
celestialApparentSizeFactor |
4000.0 |
Celestial body apparent size factor |
celestialApparentSizeMin |
1.024 |
Minimum apparent size clamp |
FOV-Aware Rendering
Stars use a custom shader that separates each point into position and offset:
| Attribute |
Meaning |
Behavior |
Position (vec3) |
Celestial sphere coordinate, shared by 4 vertices |
Transformed by MVP, naturally affected by FOV |
Offset (vec3) |
Billboard corner offset, unique per vertex |
Multiplied by FovCompensation for size correction |
Formula: FovCompensation = tan(fov/2) / tan(35°) × strength + (1 - strength)
Shader: worldPos = Position + Offset × FovCompensation
Per-Star Brightness
Based on Vmag with independent decay thresholds:
| Parameter |
Formula |
Notes |
| Alpha |
clamp(1 - max(0, Vmag-3)/12, 0.4, 1) |
Full brightness at Vmag ≤ 3 |
| RGB |
clamp(1 - max(0, Vmag-1)/19, 0.7, 1) |
Full brightness at Vmag ≤ 1 |
| Size |
clamp(1 - Vmag/12, 0.5, 1) × starCoreSize |
Larger Vmag = smaller dot |
Glow quads only for Vmag < 2.0: < 0.5 → high / < 1.5 → medium / < 2.0 → low.
Data Pack — Celestial System
Path: data/readstar/celestial/system.json
Place at saves/<world>/datapacks/<pack>/data/readstar/celestial/system.json or server world/datapacks/.
Structure
{
"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>": { ... } }
}
}
}
Field Reference
| Field |
Description |
mass |
Mass (kg). 0 = fixed at parent position |
radius |
Radius (m). Apparent size = max(1.024, radius / distance × factor) |
luminance |
Self-luminosity 0~15. >0 = star; children auto-resolve hostStar upward |
unstableDirtySnowball |
Comet flag. true renders dual-tail structure |
hasAtmosphere |
Has atmosphere (controls overlay and glow rendering) |
atmosphereHSV |
Atmosphere HSV color, packed int (H<<16 | S<<8 | V). H=hue, S=saturation, V=density (0~255) |
starHSV |
Body's own color, same encoding. Luminous = emission, non-luminous = surface reflection |
axis |
Rotation axis. Zero vector defaults to (0,0,-1) |
orbit.semiMajorAxis |
Semi-major axis (m). 0 = no orbit |
orbit.eccentricity |
Eccentricity. 0 = circular |
orbit.inclination |
Orbital inclination (radians) |
orbit.argumentOfPeriapsis |
Argument of periapsis (radians) |
orbit.longitudeOfAscendingNode |
Longitude of ascending node (radians) |
orbit.initialMeanAnomaly |
Initial mean anomaly (radians) |
Names are case-insensitive. children: {} = no children. Nesting depth is unlimited.
Complete Example
Sun → Earth + Mars → Moon. Real solar system data.
{
"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": {}
}
}
}
}
}
Inheritance & Time
hostStar: resolved recursively upward to nearest luminance > 0 ancestor
- Position =
parent.position + orbit(parent.mass, gameTime)
- Root fixed at
(0, 0, 0)
gameTime drives orbital motion; daylightTime (0~24000) drives rotation/zenith
- Moon phases auto-computed from observer-satellite-star geometry
Atmosphere System
Each body can define atmosphere color (HSV) and its own color (HSV), both as packed ints:
atmosphereHSV / starHSV = (H << 16) | (S << 8) | V
| Component |
Bits |
Range |
Meaning |
| H (Hue) |
16-23 |
0~255 |
Hue (0=red → 255 wraps to red) |
| S (Saturation) |
8-15 |
0~255 |
Saturation (0=gray, 255=pure color) |
| V (Value) |
0-7 |
0~255 |
Density/brightness (atmosphereHSV=density, starHSV=brightness) |
Example values:
| Body |
atmosphereHSV |
starHSV |
Notes |
| Sun |
0 |
2172671 |
No atmosphere, G-type yellow-white |
| Earth |
9738751 |
9732275 |
Blue sky (H=0.58, S=0.6, V=1.0) |
| Mars |
1336835 |
1356697 |
Faint red-brown (V=0.01, very thin) |
Pack/unpack via CelestialBody.packHSV(h, s, v) and getHueFloat/getSaturationFloat/getValueFloat.
Glow computation (computeGlowColor): halo color = starlight × atmospheric scattering. Hue shifts toward atmosphere; saturation and brightness slightly boosted.
Rendering layers:
1. renderSkyDisc → vanilla biome sky background
2. Bodies + stars → luminous / non-luminous + star catalog
3. renderAtmosphereOverlay → translucent full-sky atmosphere (fades at night)
Celestial Textures
Body textures are organized by category, auto-discovered by celestial.json atlas:
assets/<namespace>/textures/environment/celestial/
├── luminous/<name>.png # Luminous bodies (single image, no phases)
├── non-luminous/<name>/ # Non-luminous bodies (8 moon phase PNGs)
└── halo.png # Glow texture (grayscale radial falloff)
Luminous bodies need one PNG in luminous/. Non-luminous bodies need 8 moon phase PNGs in non-luminous/<name>/. readstar:luminous/white_sun.png is a placeholder — replace with your own.
Resource Pack
Star Catalog
Path: assets/readstar/custom/stars/stars.json
Data Sources
Star catalogs are auto-generated by scripts in .data/:
| Script |
Source |
Output |
generate_stars.py |
BSC5 Bright Star Catalogue |
stars_named.json (361 IAU-named) + stars_numbered.json (8043 HR-numbered) |
gaia_download.py |
Gaia Archive TAP API |
gaia_bright_with_teff.vot (with effective temperature) |
gaia_to_stars.py |
Gaia DR3 + BSC5 fallback |
stars_gaia_named.json (361) + stars_gaia_numbered.json (11809) |
Color pipeline: Prefer Gaia GSP-Phot effective temperature → Planckian blackbody → sRGB; fallback to bp_rp color-index mapping. 12 brightest stars (Sirius, Vega, etc.) retain BSC5 data due to Gaia detector saturation.
JSON Format
{
"Stars": [
{
"name": "Sirius",
"position": [-0.1875, -0.2876, 0.9392],
"Vmag": -1.46,
"color": 4294967295
}
]
}
| Field |
Description |
name |
Identifier (reserved, no runtime effect) |
position |
Unit sphere direction [x,y,z], normalized to distance 100. Y=North Celestial Pole |
Vmag |
Apparent magnitude (Gaia G-band or BSC5 V-band). Determines glow tier and brightness decay |
color |
ARGB color value; key for atlas sprite generation |
Custom Moon Textures
Core feature: add 8 moon phases to any celestial body by simply placing PNG files — zero code.
Directory
assets/<namespace>/textures/environment/celestial/non-luminous/<body-name>/
<body-name> must match system.json name in lowercase
- Requires exactly 8 PNGs with fixed filenames:
| File |
Phase |
full_moon.png |
Full |
waning_gibbous.png |
Waning Gibbous |
third_quarter.png |
Third Quarter |
waning_crescent.png |
Waning Crescent |
new_moon.png |
New |
waxing_crescent.png |
Waxing Crescent |
first_quarter.png |
First Quarter |
waxing_gibbous.png |
Waxing Gibbous |
Requirements
| Spec |
Value |
| Format |
PNG, RGBA 32-bit |
| Size |
16×16 or 32×32 recommended |
| Edges |
Transparent (alpha=0) |
| Color |
Self-colored; no runtime tinting |
Example: Jupiter
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
Also define Jupiter's orbit in system.json (see example above).
How It Works
- PNGs under
textures/environment/celestial/ auto-discovered by Minecraft's atlas system
ReadstarSkyRenderer scans moons/ subdirectories and builds GPU buffers by group
- Runtime matching by
body.name
Other mods can override textures via resource pack priority.
Sprites & Atlas
Star Atlas
assets/readstar/atlases/star.json declares readstar:star source. At runtime, all color values from stars.json tint base stencils per-pixel:
| Stencil |
Path |
Purpose |
star_base.png |
textures/environment/star/ |
Core (32×32 RGBA) |
star_glow_low.png |
same |
Low glow |
star_glow_med.png |
same |
Medium glow |
star_glow_high.png |
same |
High glow |
Each color → 4 sprites: color_{c}, glow_low_{c}, glow_med_{c}, glow_high_{c}.
Requirements: RGBA 32-bit, 32×32, black edges, glow brightness suppressed ×0.35.
Celestial Atlas
assets/readstar/atlases/celestial.json uses minecraft:directory source, auto-scanning all namespaces under textures/environment/celestial/.
Network Sync
Server loads data/readstar/celestial/*.json and broadcasts via readstar:planet_system packet. Client rebuilds the celestial tree in CelestialBodyManager.initializeFromJson().
Build & Troubleshooting
./gradlew build # Build JAR
./gradlew runData # Data generation (atlas config)
./gradlew runClient # Run client
./gradlew runServer # Run server
Output: build/libs/readstar-*.jar
| Symptom |
Check |
| Purple/black star textures |
Is star_base.png 32-bit RGBA? |
| Purple moon phase |
Missing PNG or filename mismatch |
| Body not visible |
Does it have hostStar (ancestor luminance>0)? |
| Glow/halo not rendering |
Is halo.png under textures/environment/celestial/? |
| Atmosphere color wrong |
Are atmosphereHSV / starHSV packed correctly? |
| Data pack not applied |
/reload or restart |
| Resource pack not updating |
F3+T |
| FOV compensation not working |
starFovCompensationStrength > 0? |
© 2026 FrozenStream. Licensed under MIT.
评论 0
登录后参与评分
还没有评论,来抢沙发吧