PlanetsLib

Code, graphics and conventions to help modders creating planets, moons and other systems. This library is a community project and will grow over time. Contributors are welcome to open a pull request on Github. For feature requests, please open an issue.

Credits

Contributors:

• thesixthroc
• Tserup (art)
• MidnightTigger
• notnotmelon
• MeteorSwarm

Notes for contributors

• We're currently publishing releases of this mod manually. In your pull requests, please list your changes in changelog.txt to be included in the next release. Please also update README.md to add sections for your new functionality (even with only 'Documentation pending') and add yourself to the contributors list.
• You must test your changes, ideally with multiple planets installed.
• We aim to avoid any breaking changes.
• Feel free to use the file todo.md.

API Reference

Planet definitions

Planet prototypes and space location prototypes can be defined using the following API. The 'distance' and 'orientation' of the prototypes will be calculated automatically from the orbit hierarchy, as will the layering of the sprites on the starmap.

• PlanetsLib:extend(config) — A wrapper/replacement for data:extend. Throws an error if passed distance or orientation. It instead takes the fields listed below.
  • type — "planet" or "space-location"
  • orbit — Object containing orbital parameters:
    • parent — Object containing name and type fields, corresponding to a parent at data.raw[type][name]. Planets in the original solar system should have an orbit with type = "space-location" and name = "star".
    • distance — Number: orbital distance from parent
    • orientation — Number: orbital angle from parent (0-1). Note that orientation is absolute, not relative to the parent's orientation.
    • sprite — Object (optional): Sprite for the planet’s orbit, centered on its parent.
  • sprite_only — Boolean (optional): If true, this prototype will be removed in data-final-fixes and replaced by its sprites on the starmap (unless neither starmap_icon, starmap_icons nor an orbit sprite are defined, in which case nothing will show).
    • This is useful for constructing stars and other locations that should not have a space platform 'docking ring'.
  • Other valid planet or space-location prototype fields
  • Further notes on PlanetsLib:extend:
    • Should not be called in data-final-fixes.
    • See here or here for usage examples.
• PlanetsLib:update(config) — The same as PlanetsLib:extend, except it updates a pre-existing planet or space location (identified by the passed type and name fields) using the parameters passed. If the orbit field is passed, the distance and orientation fields on the prototype will be updated appropriately. Should not be called in data-final-fixes.

Planet Cargo Drops technology

The library provides automatic functionality to restrict cargo drops on your planet until a technology is researched. To implement:

• Use the helper function PlanetsLib.cargo_drops_technology_base(planet, planet_technology_icon, planet_technology_icon_size) to create a base technology prototype.
  • This will create a technology with name pattern: planetslib-[planet-name]-cargo-drops
  • PlanetsLib detects this technology by name. Players will be unable to drop cargo (excluding players and construction robots) to planets with that name before researching the technology.
  • Only the fields type, name, localised_name, localised_description, effects, icons will be defined, so you will need to add unit (or research_trigger) and prerequisites.
  • A locale entry for this technology is automatically generated, but you are free to override it.

Support for moons

• PlanetsLib.technology_icons_moon — Icon to be used in moon discovery technologies.
• subgroup=satellites — A new Factoriopedia row for satellites (below the planets row).

Description templates

Documentation pending.

Surface conditions

Restricting and relaxing conditions

Typically, when planet mods want to add a surface condition, what they are trying to do is restrict or relax the range of values for which that recipe or entity is allowed.

For example, Space Age recyclers have a maximum magnetic field of 99. If mod A wants to allow recyclers to be built up to 120, whilst mod B wants to allow them up to 150, compatibility issues can arise if mod A acts last and overrides mod B's change (which it ought to have been perfectly happy with). Instead mod A should modify existing surface conditions only if necessary.

Hence relax_surface_conditions and restrict_surface_conditions are provided, used like so:

• relax_surface_conditions(data.raw.recipe["recycler"], {property = "magnetic-field", max = 120})
• restrict_surface_conditions(data.raw.recipe["boiler"], {property = "pressure", min = 10})

NOTE: Calling relax_surface_conditions without a min field will not remove any existing min conditions for that property (and similarly for max).

New surface conditions

PlanetsLib includes a variety of surface conditions, all of which are either hidden or disabled by default. To enable a surface condition, modders must add the following line to settings-updates.lua (using 'oxygen' as an example):

data.raw["bool-setting"]["PlanetsLib-enable-oxygen"].forced_value = true

Per-planet restrictions

• PlanetsLib.restrict_to_planet(entity_or_recipe, planet): Restricts the entity or recipe prototype to a given planet by adding a special surface condition unique to that planet. This surface condition is almost invisible in the UI, with the exception of messages like "X can't be crafted on this surface. The is too low". The planet can be passed as a name or object.

Other helper functions

• PlanetsLib.set_default_import_location(item_name, planet) - Sets the default import location for an item on a planet.
• PlanetsLib.borrow_music(source_planet, target_planet) - Clones music tracks from source_planet to target_planet. Does not overwrite existing music for target_planet.

Python helper scripts

• lib/orbit_graphic_generator.py: contains a Python script that generates orbit sprites. generate_orbit(distance, output_file, mod_name), distance being the same as your orbital distance. After generating your sprite, the script will print a block of lua code that imports your sprite with proper scaling. Orbit sprites should be scaled at 0.25 to ensure that no pixels are visible, even on 4K displays.