轨道形状库 Orbit Shapes

61231345

一句话给 mod 作者用的纯库：让天体走真正的开普勒椭圆（吸引体在焦点，近星点快、远星点慢），并让渲染器能画出真实轨道形状，而不是一律画圆。零依赖、零游戏内容、不改动任何原版文件。


实际画面：
[url=]Starsector 0.98a-RC8 2026 ...[/url]

同日发布的另一帖《轨道线显示 Orbit Lines》是配套的显示 mod，本库只提供轨道形状，画线由它负责。

轨道线显示 Orbit Lines
http://www.fossic.org/thread-21979-1-1.html

基本信息

• 适配版本：Starsector 0.98a-RC8
• 版本：0.1.0　|　mod id：orbit_shapes
• 依赖：无　|　许可：MIT　|　作者：梁公子
  

为什么需要它原版只支持圆轨道。字节码实证：引擎的 getCircularOrbitRadius / Period / Angle 只对 CircularOrbit 系列返回非 0，其它实现一律返回 0，而全引擎有 63 处调用依赖这三个值（主题生成、命名、任务、市场等）。自己写一个 OrbitAPI，游戏会把该天体当成「没有轨道」。本库的 KeplerOrbit 继承 CircularOrbit 并覆写必要方法，instanceof 检查照常通过，63 处调用照常工作。提供两样东西

• KeplerOrbit：真开普勒椭圆。吸引体在焦点；平均近点角 M 匀速推进，解开普勒方程 E − e·sinE = M 得到位置，自动实现近星点快、远星点慢、等时扫过等面积。
• PathOrbitAPI：轨道形状采样接口。渲染器只要会问「给我一条折线」就能画出真实形状；别的 mod 也能给自己的轨道类型实现它。
  

给 mod 作者：最短只要 a 和 e

1. import aashapes.orbit.KeplerOrbit;// 焦点默认取星系中心；周期直接给planet.setOrbit(KeplerOrbit.forSystem(planet, system, 4000f, 0.35f, 0f, 181.8f));// 或者按开普勒第三定律，连周期都不用给float GM = 7.643022e7f;   // 1 太阳质量，按原版 procgen 标定planet.setOrbit(KeplerOrbit.forSystemByThirdLaw(planet, system, 4000f, 0.35f, 0f, GM));// 完整参数：天体 / 焦点 / 半长轴 a / 偏心率 e / 近日点幅角 w / 周期 / 初始角planet.setOrbit(new KeplerOrbit(planet, star, 4000f, 0.35f, 30f, 220f, 0f));

复制代码

焦点是对象引用（SectorEntityToken），不是 id 也不是数字，和原版 setCircularOrbit 的约定一致。「星系中心」= system.getCenter()：单星系统就是那颗星；共同质心双星里是那个空中心 token，天体自动成为共轨行星。依赖方式

• 硬依赖：在 mod_info.json 里写 "dependencies": [ { "id": "orbit_shapes", "name": "轨道形状库 Orbit Shapes" } ]
• 软依赖：用 isModEnabled("orbit_shapes") 分支，没装就退回 setCircularOrbit。Java 类解析是惰性的，不执行那行就不会抛 NoClassDefFoundError。
  

渲染器：拿真实轨道形状

1. Vector2f[] path = null;try {    path = aashapes.orbit.OrbitShapesUtil.getPathFor(entity, 64);} catch (Throwable ignored) {    // 库没装}if (path != null) drawPath(path);else               drawCircle(entity.getCircularOrbitRadius());

复制代码

getOrbitPathOffsets(n) 返回相对焦点的采样点。椭圆形状恒定，算一次缓存起来，之后每帧只需按焦点位置平移。数值与正确性

• 单位：长度 px、时间天、角度度；GM 单位是 px³/day²，不要把真实太阳的 GM 代进来。
• 推荐基准 GM = 7.643022e7（1 M☉），由原版 procgen 的 orbitDays = orbitRadius / 22 在 a=4000 处反推，此时周期 181.8 天。注意它只是单点锚定：原版是 T ∝ a，第三定律是 T ∝ a^1.5，两者只在 a=4000 重合。
• 每次启动自动跑 5 项数值自检，日志搜 "OrbitShapes self check"：椭圆恒等式、开普勒第二定律、近远星点、一周期扫面积、角度往返，游戏 JVM 内 5/5 PASS。
• 性能：单实体约 249 ns/帧，100 个约 24.9 µs/帧；采样 64 段约 4.54 µs/实体，缓存后每帧近乎零成本。
  

已知限制

• 引擎自己画的轨道线仍是按半长轴画的圆；要画真椭圆请用 PathOrbitAPI。
• 舰队轨道（CircularFleetOrbit）是另一个类，本库不提供舰队用椭圆。
• 轨道对象由 XStream 序列化：用它生成过轨道的存档必须保留本库，停用后读档会失败；但生成内容的那个 mod 可以随意卸载。
• selftest.json 默认关闭；打开后可把指定天体套上椭圆，用来观察 setOrbit / advance / 存档序列化的实际表现。
  

下载与安装【下载直链：Aa-OrbitShapes_v0.1.0.zip】解压后把 Aa-OrbitShapes 文件夹放进 <游戏目录>/mods/，在启动器里勾选即可。包内 README.md 有完整 API 与数值参考，data/config/orbitshapes/README.txt 有引擎兼容要点，LICENSE 是 MIT。v0.1.0，首个公开版本。这是给 mod 作者用的库，普通玩家不装也完全不影响原版游戏；如果你在自己的 mod 里接入了它，欢迎回帖说 API 是否顺手、有没有遇到引擎兼容性问题。