Adding a planet

Adding a Planet

This page walks through everything needed to add a new celestial body to Orrery. Most of the work is standard Minecraft datapack content (dimension, biome, worldgen); Orrery-specific work is limited to one JSON file (PlanetData) and, optionally, registering a block set if the planet needs its own materials.

No new Mixins or Java code are required for a standard planet. Generic Mixins already read from the planet registry described below.

Overview of the workflow

1. Create the dimension, dimension type, and biome JSON files (standard Minecraft worldgen)
2. Create a PlanetData JSON describing gravity, sky appearance, and other properties
3. (Optional) Register a block set — stone, sand, and ore variants — if the planet needs unique materials
4. Test in-game: world load, sky rendering, gravity/fall damage, telescope entry Each step is detailed below using a hypothetical planet, Ceres, as a running example.

Step 1 — Dimension, dimension type, and biome

These follow standard Minecraft/NeoForge conventions and aren't Orrery-specific. You'll need:

• data/orrery/dimension/ceres.json — the dimension definition, referencing a dimension type and noise settings
• data/orrery/dimension_type/ceres.json — dimension type (height limits, sky lighting, etc.)
• data/orrery/worldgen/biome/ceres_surface.json — the biome used for the planet's surface
• data/orrery/worldgen/noise_settings/ceres.json — terrain shape and surface rules If the planet should have a curated surface (no unwanted vanilla/Terralith structures, but specific structures allowed — e.g. meteorites), set:

"features": [[], [], [], [], [], [], [], [], [], [], []],
"structure_starts": [
  "ae2:meteorite"
]

in the biome JSON. This blocks all structure generation except the ones you explicitly list.

If using a minecraft:fixed biome source, Terralith and similar worldgen mods generally won't inject content into your biome, since they target tagged vanilla biomes. Avoid adding tags like #minecraft:is_overworld unless you specifically want that interaction.

Step 2 — The PlanetData JSON

This is the core Orrery-specific file. Create it at:

data/orrery/orrery_planets/ceres.json

The filename doesn't need to match the planet name, but it's good practice. On every resource reload (including world load), Orrery loads every file under orrery_planets/ in any namespace, parses it, and registers the resulting PlanetData in the planet registry.

Example

{
  "dimension": "orrery:ceres",
  "planet_name": "ceres",
  "gravity": 0.029,
  "has_oxygen": false,
  "temperature": -106,
  "atmosphere_cost": 0,
  "computing_cost": 600,
  "engine_constant": 12.0,
  "sun_multiplier": 0.3,
  "has_sky": true,
  "can_see_sky_at_day": true,
  "has_weather": false,
  "seed_offset": 5,
  "is_in_orbit": true,
  "wind_multiplier": 0.0,
  "sky": {
    "has_stars": true,
    "star_brightness": 0.9,
    "sun_brightness": 0.5
  }
}

Field reference

Field	Type	Description
dimension	string	The dimension key, e.g. "orrery:ceres". Must match your dimension JSON's location.
planet_name	string	Internal name used by Northstar's planet lookups (e.g. for rocket destination selection).
gravity	double	Surface gravity as a fraction of Earth's (1.0 = normal). Drives both Northstar's gravity mechanics and Orrery's fall damage scaling.
has_oxygen	bool	Whether the planet has a breathable atmosphere.
temperature	int	Surface temperature, used by Northstar's temperature systems.
atmosphere_cost	int	Resource cost for atmosphere-related mechanics (e.g. atmospheric concentrator).
computing_cost	int	Computing cost for rocket navigation/landing on this planet.
engine_constant	double	Engine performance constant for rocket travel calculations.
sun_multiplier	float	Northstar's internal sun-strength multiplier (affects solar panel output, etc.) — distinct from the sky renderer's sun_brightness.
has_sky	bool	Whether Orrery's custom sky renderer applies to this dimension at all.
can_see_sky_at_day	bool	Whether the sky is visible during the day cycle.
has_weather	bool	Whether rain/snow weather can occur.
seed_offset	long	Offset applied to the world seed for this dimension's terrain generation, so it differs from other planets sharing the same base seed.
is_in_orbit	bool	Marks the dimension as an orbit-type location for Northstar's systems.
wind_multiplier	float	Scales wind-related effects (if applicable).
sky.has_stars	bool	Whether stars render in the custom sky.
sky.star_brightness	float	Base star brightness (combined with the in-game day/night cycle — see note below).
sky.sun_brightness	float	Brightness multiplier for the rendered sun disc. Lower values suit planets far from the Sun.

A note on sky.star_brightness: the actual rendered brightness is star_brightness - (vanillaStarBrightness * 0.5), where vanillaStarBrightness follows the normal day/night cycle. This means stars are brightest during the in-game "day" and dim slightly at "night" — intentionally inverted from an Earth-like sky, since on an airless world stars are always visible regardless of the sun's position.

Fall damage

Fall damage is not a field in PlanetData — it's calculated automatically from gravity. The effective fall distance is actualFallDistance * gravity, compared against the normal 3-block safe-fall threshold. Lower gravity means players can fall much further before taking damage, with no extra configuration needed.

Step 3 — Block set (optional)

If your planet needs its own stone, sand, and ore blocks (matching its surface material and visual identity), register a block set in code, once, during mod setup:

OrreryBlocks.registerPlanetBlockSet("ceres", List.of("zinc", "copper"));

This automatically registers:

• orrery:ceres_stone
• orrery:ceres_sand
• orrery:ceres_zinc_ore
• orrery:ceres_copper_ore with block items, datagen-produced models (using ore overlay textures — see Block sets and datagen), language entries, tags, and loot tables.

You only need to supply:

• assets/orrery/textures/block/ceres_stone.png
• assets/orrery/textures/block/ceres_sand.png Ore overlay textures are shared across all planets — if zinc and copper overlays already exist from another planet, they're reused automatically.

If your planet's surface uses an existing block (e.g. Northstar's moon sand, as Eris does), you can skip block set registration entirely and reference the existing block ID directly in your surface rules.

Step 4 — Testing

1. Launch the game and check the log for [Orrery] Loaded planet: ... confirming your PlanetData JSON parsed successfully. Parse errors are logged as [Orrery] Failed to parse planet ... with details.
2. Use /orrery in-game to confirm the planet appears in the registry with the expected values.
3. Travel to the dimension (via creative /execute in <dimension> run tp ... for early testing, before rocket travel is set up) and verify:
   • The custom sky renders correctly (black sky, stars, dimmed sun if has_sky is true)
   • Gravity feels correct and fall damage scales as expected
   • Worldgen produces the intended terrain and structures
   • The planet appears correctly in the Telescope

Common pitfalls

• Dimension key mismatch — PlanetData.dimension must exactly match the dimension JSON's resource location (<namespace>:<path>), including namespace. A common mistake after renaming a mod ID is leaving stale references to the old namespace.
• Missing sky object — if has_sky is true but the sky object is malformed or missing required fields, the JSON will fail to parse entirely (not just the sky portion), and the planet won't register at all. Check logs for parse errors.
• Reload listener registration — PlanetDataLoader must be registered via AddReloadListenerEvent for any orrery_planets JSON to be picked up. This is a one-time setup already done in Orrery's main mod class — not something you need to repeat per planet.
• Stale registry on reload — PlanetRegistry is cleared and rebuilt on every resource reload. If you're testing with /reload in-game, make sure all your planet JSONs are present and valid each time, since a parse failure in one file doesn't roll back previously loaded planets from that same reload pass but won't add the broken one either.