Documentation for lualib libraries is missing

[jDomantas]

Libraries in core/lualib can be imported by mods, but I can't find any documentation for them. It looks like they are supposed to be usable by scripts ("collision-mask-util" is mentioned in FFF-362, "story" is described in scripting tutorial), but if that's the case then they are very difficult to discover and figure out how to use. I only found out about them while reading the source for Story Missions mod.

[Hares]

Similar topic: viewtopic.php?f=25&t=91536

Instant +1 on that.

[Deadlock989]

+1. I've been misled or made faulty assumptions a few times. Prime candidate would be resource_autoplace.

[Bilka]

Documenting the contents of the lualib libraries is in our longterm plan. For now you'll have to make do with the comments in the files/their source code.

+1. I've been misled or made faulty assumptions a few times. Prime candidate would be resource_autoplace.

Could you expand on specific issues/information that you discovered? A first version of the docs would mostly copy the comments found in the Lua files, and I assume those were not enough to address what you encountered.

[Hares]

Documenting the contents of libraries in our longterm plan. For now you'll have to make do with the comments in the files/their source code.

+1. I've been misled or made faulty assumptions a few times. Prime candidate would be resource_autoplace.

Could you expand on specific issues/information that you discovered? A first version of the docs would mostly copy the comments found in the Lua files, and I assume those were not enough to address what you encountered.

I assume this COULD be a task for the community -- ask modders to write docs for the functions they know, and then compile it to something more readable.

[Deadlock989]

Could you expand on specific issues/information that you discovered? A first version of the docs would mostly copy the comments found in the Lua files, and I assume those were not enough to address what you encountered.

The most recent cock-up I made was trying to use collision_mask_util.get_first_unused_layer(). I didn't see any comments because I was going from examples provided by Wube staff elsewhere (looking at the source file, it turns out there are none). I didn't realise that you have to put the result into a data.raw prototype more or less immediately, since otherwise get_first_unused_layer() will simply return the same layer again.

The util functions ... There are very few comments. I didn't know util.copy exists and didn't realise it was identical to table.deepcopy. I didn't realise util.mix_color multiplies two colours, I assumed it would produce the mean colour. I didn't know util.direction_vectors existed and have made my own version several times. Even a simple centralised list of available named functions without any further decoration would be better than having to scroll through 700 lines of code and figuring each one out.

With resource_autoplace ... I mean, just all of it. What is base_density - it says "amount of stuff, on average, to be placed per tile" which is very vague. How is that different to base_spots_per_km2? I thought I knew what richness was until I actually started to look at the comments which made me realise I clearly didn't, so what is it? Why does crude oil have additional_richness of 220000, what is that magic number? It's very frustrating to trial-and-error resource autoplace specs when you have to restart the game and generate map previews every time you make a tweak. Typically people come to this stuff thinking "I want blobs of infinite resource X that are roughly spaced Y tiles apart and start off at 100% yield if the slider is 100% richness" but getting to that result from existing examples and comments takes tens of hours to get right when it should take 10 minutes.