planets

#planets.airAt(position: vec3): number

Air density at a position (absolute), kg/m³: 1.225 at Earth's sea level, 0 in space.

#planets.define(map: string, body: any)

Adds one planet to a map's system (the map file's, or the one planets.system set), with the fields of a "bodies" entry. Load phase only, like planets.system.

planets.define("twin-worlds", { name = "Cinder", radius = 8000, position = { 60000, -8000, 0 }, atmosphere = false })

#planets.gravityAt(position: vec3): vec3

Gravity at a position (absolute), m/s², pointing down. Sums every planet in reach; flat maps return the game's flat gravity.

local g = planets.gravityAt(maps.spawnPoints()[1])
log.info("down: " .. tostring(g))

#planets.list(): any

Every planet of the current map as { name, radius, position, gravity, gravityReach, atmosphereHeight, airDensity } (absolute positions, metres, m/s², kg/m³).

for _, p in ipairs(planets.list()) do log.info(p.name .. " " .. p.radius) end

#planets.nearest(position: vec3): table?

The planet whose surface is nearest a position (absolute), as planets.list describes it, or nil on a map without planets.

#planets.resetWeather()

Puts the weather back to what the server had before the map (or planets.setWeather) changed it.

#planets.setWeather(weather: any)

Sets the world's weather for everyone: a preset ("temperate", "arid", "stormy", "frozen", "clear") or { preset, …fields } with the map file's weather fields (stormCount, wetness, temperatureOffset, mode, …). Put back when the map is left.

planets.setWeather({ preset = "frozen", stormCount = 2 })

#planets.system(map: string, spec: any)

Sets the planet system of one of this mod's maps, exactly like the map file's "system" section (same fields, same checks). Only while the mod's scripts first run (the load phase): the world must be decided before anyone builds it. Call it from a SHARED script (mod.json entry.shared) so the server and every player build the same planets — a server whose system differs from a player's disconnects that player.

planets.system("twin-worlds", {
  weather = "stormy",
  bodies = {
    { name = "Ember", radius = 20000, position = { 0, -20000, 0 } },
  },
})

#planets.trySetWeather(weather: any): boolean, string?

Like planets.setWeather, but a refusal returns false and the reason instead of raising an error. Wrong arguments, side and permission errors still raise.

Returns true and the result on success; false and the reason on a refusal.

planets.setWeather({ preset = "frozen", stormCount = 2 })

#planets.weather(where: any): table?

The weather on a planet (by name, at its weather focus — where the players are) or at a position, as { planet, rain, snow, temperature, cloud, wind } (mm/h, °C, 0..1 cover, m/s). nil where there is no weather (no air, weather off).

local w = planets.weather("Ember")
if w and w.rain > 2 then log.info("it is pouring") end