Factorio Forums

For example, in the case of LuaSurfacePrototype’s surface_properties, I couldn’t find anywhere what values are allowed. I only figured out what can be applied after looking through vanilla data and other mods.

Similarly, there seem to be many other dictionary objects where the valid inputs are not clearly documented. I will add more examples if I find them.

Doesn't your given example describe what it takes?
https://lua-api.factorio.com/latest/cla ... properties It displays as dictionary[SurfacePropertyID -> double] for me
Meaning that the keys are SurfacePropertyID's with their values being a double

As a sanity check, I went back to 2.0.7's version of the docs and it remains unchanged


Or do you mean you don't know what *values* SurfacePropertyID can be? In which case it depends on what SurfacePropertyPrototype's have been defined

For example, the dictionary I mentioned above actually contains the following values when checked in-game.
I'm not sure where specific valid entries such as day-night-cycle, magnetic-field, solar-power, pressure, and gravity are documented in the API. Also, when looking at other modded planets, it seems possible to define additional attributes such as temperature, but I couldn’t find any mention that these are actually allowed. Wouldn’t it be better if these details were documented more thoroughly?

While referring to other people’s code or vanilla data is certainly a good way to learn, I think it’s a bit strange that such information is missing, considering the purpose of the documentation. If there is an implementation that isn’t used in the vanilla code and it’s also not documented, we’ll never be able to make use of it.

Those aren’t “keys”, they are names of other prototypes and as such any mod can make their own and add them there.

Documenting it would be like documenting all of the possible item names that can be part of a recipe’s ingredients - “any item”.

It already is: “any surface property ID”

Xeon257 wrote: Mon Oct 13, 2025 10:37 am I'm not sure where specific valid entries such as day-night-cycle, magnetic-field, solar-power, pressure, and gravity are documented in the API. Also, when looking at other modded planets, it seems possible to define additional attributes such as temperature, but I couldn’t find any mention that these are actually allowed. Wouldn’t it be better if these details were documented more thoroughly?

Like I said, there's the SurfacePropertyPrototype, which means to document what values the id could be would be like documenting what items exist, which is fundamentally impossible for the documentation to know.

It is outside the scope of the documentation to describe what it is ultimately used to make.
It can provide examples of how to use it, but there are little to no guarantees of what prototypes exist.

There something to be said about how it should document which ones are required in the prototype page though.
I'm not actually sure if the relationship between a few key surface properties and robot energy consumption is documented anywhere. If it is, it should probably get references in multiple places key two places being the SurfacePropertyPrototype (and Lua pair) and FlyingRobotPrototype.

Regardless. There's only one place you need to look in the base game to see what surface properties it defines.
https://github.com/wube/factorio-data/b ... operty.lua

It is possible to disable the base mod, albeit unlikely, so the API documentation is built to assume it does not exist. With the few exceptions being explicitly stated when specially relevant.

Ah… to summarize,

1. The API documentation is mostly auto-generated. Because of this, the system can’t fully track which keys a specific dictionary can contain or how they’re used.

2. The API itself is written to be neutral — even for vanilla — so it’s more accurate to look at the vanilla source definitions than to expect every internal detail to appear in the API docs.

Is this understanding correct? I’m not very familiar with how such a large program is structured, so I just want to make sure I’ve got it right.

The keys for the dictionary are defined by the documentation. It's "the names of all prototypes of this type". What prototypes of that type exist depends entirely on what prototypes your mod and any other mod in the game have created. If you want to find out what prototypes are in your game with your current mods, you can use the prototype explorer. Start the game, open a save file and press CTRL + SHIFT + E to open it. Then you can see all the prototypes.

I understand now — I was asking for something that obviously wouldn’t be included in the documentation. That was my mistake! Thank you very much for taking the time to explain it in detail.

I was asking for something that obviously wouldn’t be included in the documentation.

Actually, since the api does document types like float and unit32, it would make sense to have a page for the "dictionary" type, similar in nature to the page for LuaCustomTable. Dictionary isn't a word used in Lua and it may be unfamiliar to those who didn't have knowledge about the concept from other places.