@@MDPLACEHOLDER_0@@@@MDPLACEHOLDER_1@@@@MDPLACEHOLDER_2@@

PlanetsLib

Code and graphics to help modders creating planets, moons and other systems. This library is a community project. Anyone is welcome to open a pull request on Github. For feature requests, please open an issue. For general discussion, use Discord.

Since other mods make use of the 'orbit structure' this mod provides to the solar system, it is recommended to add PlanetsLib compatibility to your planet mod either by defining your planet prototype using PlanetsLib (as in the first image in the mod portal gallery), or by calling PlanetsLib:update in data-updates.lua (second image in the gallery). Besides improving compatibility with PlanetsLib consumers, this means if another mod updates the position of your planet's orbital parent without moving your planet, your planet will be moved too.

We aim to never make any breaking API changes such that the library is safe to use. We sometimes deprecate APIs by removing them from the documentation, but they stay functional.

Player-facing features

The primary intent of PlanetsLib is to be a library which provides opt-in functionality for other mods. However, a small number of game-affecting or player-interface-affecting features have been added over time. These are listed below, player feedback on them is most welcome in Discord.

• Unlinking hidden prerequisites
• If PlanetsLib detects that technologies have hidden prerequisites such that they would be unresearchable, it warns players about this fact.
• This is done because the Factorio client gives no explanation or reason for why these technologies cannot be researched.
• There are PlanetsLib mod settings to repair the user's game by unlinking all such prerequisites, or to disable the warning.
• Fixed rocket weights of vanilla items
• If an item prototype does not have an explicitly specified rocket weight, the behavior of the Factorio engine is to assign it a weight based on the recipes that produce it. Unfortunately, this means that the rocket weight of vanilla items is liable to change when additional mods are installed. PlanetsLib therefore sets an explicit weight on vanilla items equal to their weight in Space Age. This occurs in data-final-fixes and only if the item does not have a weight by that point.
• Extra informational tooltips
• On recipes:
• Freshness resets on craft completion
• This tracks result_is_always_fresh and only appears if true.
• Freshness resets on craft beginning
• This tracks reset_freshness_on_craft and only appears if true.
• Products preserved in machine output
• This tracks preserve_products_in_machine_output and only appears if true.
• On entities:
• Energy to heat up
• This tracks heating_energy and only appears if defined.
• All such tooltips are added in data-final-fixes.
• Biolab inputs
• Because modders often forget about the Biolab when adding a new science pack, PlanetsLib mirrors all science packs from the vanilla lab to the Biolab in data-final-fixes.
• Centrifuge entity improvements
• This entity is given an input and an output fluidbox (or two of each if the mod setting PlanetsLib-enable-additional-centrifuge-fluidboxes is enabled).
• Also, the graphics of the working glow are improved so that it naturally glows different colors depending on the recipe.
  

Notes for contributors

• 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.
• Contributions MUST be tested before a PR is made, ideally with multiple planets installed.
• Feel free to use the file todo.md.
  

API documentation

Defining planets

PlanetsLib provides an API to define planets and space locations. It is a simple wrapper for data:extend.

The reasons one may choose to use it over a plain data:extend are some additional features: you can specify positions with respect to a parent body; if the parent body is moved by another mod your planet will move with it; a sprite depicting the orbit can be supplied; and various other mods are sensitive to the orbit tree.

• PlanetsLib:extend(configs) — Throws an error if passed distance or orientation. (as these will be generated automatically on the prototype.) Instead, it takes the following fields:
• 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. This will be centered on the parent's location. If the parent is a planet that becomes hidden, the orbit sprite will not be drawn.
• type — "planet" or "space-location"
• sprite_only — Boolean (optional) — If true, this prototype will be removed in data-final-fixes and replaced by its sprites on the starmap (unless it has no sprites, in which case nothing will show).
• This is useful for constructing stars and other locations that should not have a space platform 'docking ring'.
• is_satellite — Boolean (optional) — Has no effect in PlanetsLib, but other mods such as Redrawn Space Connections are sensitive to this field. (Conventionally, such mods also treat subgroup = "satellites" planets as satellites, this is the legacy marker.)
• Any other valid planet or space-location prototype fields.
• See here or here for usage examples.
• PlanetsLib:update(configs) — Updates the position of a pre-existing space location, as identified by the passed type and name fields. Any other fields passed will be updated on the prototype, and if the orbit field is passed the distance and orientation fields on the prototype will also be updated, along with the distance and orientation of its children and grandchildren. Any fields not passed will be left unchanged.
  

PlanetsLib has some extra compatibility code in data-final-fixes in which if a planet has noticed to have a position and orientation different from that implied by its orbit fields, those values will be treated as authoritative, its orbit field will be updated, and a simulated PlanetsLib:update call will be made to update the position and orientation of its children. However, using PlanetsLib:update to update planetary positions is generally recommended.

Please note that the orbit structure does not yet dictate layering of the sprites on the spacemap – this is a desired feature from future contributors, it has not been built yet.

Neither PlanetsLib:extend nor PlanetsLib:update should be called in data-final-fixes.

Planet tiers

The companion mod PlanetsLib: Tiers defines 'tier values' for planets and space locations. Tiers have no functionality by themselves, but are a rough indicator where the planet fits in a vanilla-style game of Space Age for the purposes of other mods that wish to use this information.

With PlanetsLib: Tiers installed, tiers can be accessed with local tier = data.raw["mod-data"]["PlanetsLib-tierlist"].data[type][name] or data.raw["mod-data"]["PlanetsLib-tierlist"].data.default

The tier listing is here on GitHub.. Players are encouraged to submit edits to keep it up-to-date.

Planet Cargo Drops technology

You can use the library to restrict cargo drops on your planet until a certain 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.
• It's possible to add items to cargo drop whitelists using the following APIs ('entity type' refers to the type of the entity with the same name as the item):
• PlanetsLib.add_item_name_to_planet_cargo_drops_whitelist(planet_name, item_name)
• PlanetsLib.add_entity_type_to_planet_cargo_drops_whitelist(planet_name, entity_type)
• PlanetsLib.add_item_name_to_global_cargo_drops_whitelist(item_name)
• PlanetsLib.add_entity_type_to_global_cargo_drops_whitelist(entity_type)
• Note that players can use this mod to disable the effect of this re