Friday Facts #294 - Blog thoughts & Lua documentation improvements

Regular reports on Factorio development.
Hayertjez
Inserter
Inserter
Posts: 23
Joined: Mon Oct 26, 2015 3:49 pm
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by Hayertjez »

Simply love reading fff thanks for writing them. :D

User avatar
TxT
Burner Inserter
Burner Inserter
Posts: 11
Joined: Sat Jan 27, 2018 9:36 am
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by TxT »

I always like the Friday Facts, maybe when there aren't any new shiny features to show you could give a little insight in what you did in the bugfix and optimization department.
Maybe you could talk about some interesting bugs you found and (if possible and it makes sense) show some code as well.
That could look something like that: Here is a bit of code, something in here doesn't quite work as it should, can you spot it? Well, this is what we had to do different.
Obviously that would only be possible in very few scenarios, but would be cool to read.
Some stats would be also cool, like how many lines of code changed, new, deleted, etc.

Huntracony
Manual Inserter
Manual Inserter
Posts: 1
Joined: Fri May 10, 2019 10:48 pm
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by Huntracony »

This feels like the right FFF to mention that I always enjoy reading them every week, even if it's just a wordy version of, "We fixed a bunch of bugs. Here's a graph showing that we fixed a bunch of bugs. There are still a bunch of bugs to fix." (I'm looking at you, FFF-285!) So, thank you all for taking the time every week.

User avatar
Impatient
Filter Inserter
Filter Inserter
Posts: 880
Joined: Sun Mar 20, 2016 2:51 am
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by Impatient »

"The Lua API documentation is one of the most valuable resources for modders."

Yes, but it is not THE most valuable resource for modders. The Lua API documentation misses a really big part. It covers what is available in the API, but in most cases it does not tell what that is used for (behavior, use cases, ... ). That knowledge is gathered by modders through experimentation or examining other modders code or reading the few articles written about modding of a certain part of the game and then it slowly trickles from modders to modders on the modding help forum. And starting to pursue an idea or trying to solve a problem usually starts with a search on google - which does not lead to the API doc - or it starts with asking a question in the modding help forum. Then the API doc is next to look up the correct names and places. And then comes experimentation. So, to be honest, the API doc's use is to get the spelling and the places right and that is usually it.

I see only two good ways to alleviate that situation:
1. The devs do document use cases and behavior in the code. These comments are then automatically moved to the API documentation when it is generated from the code.
2. An API doc that allows for contributions by modders, where they can record their knowledge and findings and write additional articles if they want to. This can be seen eg here ( https://www.php.net/manual/en/language. ... ggling.php , scroll down to the "User contributed notes" section ) at the PHP documentation and it was so successful and high quality, that Microsoft adopted it for their shitty documentation system like a decade (later|too late to be relevant on the market for web development).

I am trying to be positive here, though it gives me a sour feeling everytime you write about the API doc.

That said, factorio is great and reading about FFF-1 and thinking of the long way you went, made me smile. Keep it up guys!
Last edited by Impatient on Sat May 11, 2019 12:44 am, edited 1 time in total.

Qon
Smart Inserter
Smart Inserter
Posts: 2091
Joined: Thu Mar 17, 2016 6:27 am
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by Qon »

https://lua-api.factorio.com/latest/Data-Lifecycle.html
Doesn't contain the most important file of all. info.json (and the folder structure and naming scheme should be close by)

The event list. For some reason I always find it via the defines page. Would be nice if the defines list, for each category where applicable, could link to the actual documentation page for that category. So I wouldn't have to just read the names of the events and guess when it fires from the name and what the event table struct contains. Because I've been guessing and testing from the limited info I've found on the defines page where no onfo on what things do exists. I know now that there's an actual event list on the front page and on its own dedicated page

Impatient wrote: ↑
Fri May 10, 2019 11:20 pm
"The Lua API documentation is one of the most valuable resources for modders."

Yes, but it is not THE most valuable resource for modders.

I see only two good ways to alleviate that situation:
1. The devs do document use cases and behavior in the code. These comments are then automatically moved to the API documentation when it is generated from the code.
2. An API doc that allows for contributions by modders, where they can record their knowledge and findings and write additional articles if they want to. This can be seen eg here ( https://www.php.net/manual/en/language. ... ggling.php , scroll down to the "User contributed notes" section ) at the PHP documentation and it was so successful and high quality, that Microsoft adopted it for their shitty documentation system like a decade (later|too late to be important on the market for web development).
I disagree. The api is well structured and I get almost all my the info I need from it. But reading others code is one way to get up to speed quickly. Though you have to be careful with that though so you don't copy bad quality code into your brand new project. Also while I agree that code examples would be neat in some cases and that the few that are there are nice to have, the mod portal is already that for me and I don't think your suggestion could ever hope to match it exept for some short bits and pieces of common tricks and pitfalls. Which would still be valuable though. So I'm not against this suggestion, I'm cautiously for.

User avatar
Impatient
Filter Inserter
Filter Inserter
Posts: 880
Joined: Sun Mar 20, 2016 2:51 am
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by Impatient »

The API doc got a lot better in terms of explaining classes, functions and properties over the time. Still there is a lot to be desired.

Maddhawk
Fast Inserter
Fast Inserter
Posts: 101
Joined: Sat May 05, 2018 6:53 am
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by Maddhawk »

What I think is: Thank you. Thank you for these blog posts. They really tell a tale that I wish all studios told. They tell a tale I wish all gamers read. They tell a tale of honesty and hard work. They set, in my opinion, the gold standard for developer transparency and communication.

Merssedes
Fast Inserter
Fast Inserter
Posts: 117
Joined: Sun Oct 29, 2017 7:05 pm
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by Merssedes »

Just as suggestion for API documentation: remove list of classes and list of events from main page, leaving links and short description of what is it. They have their own pages and main page will be easier to read fully.
example

TheRaph
Fast Inserter
Fast Inserter
Posts: 221
Joined: Sun Sep 24, 2017 6:31 pm
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by TheRaph »

Qon wrote: ↑
Sat May 11, 2019 12:24 am
https://lua-api.factorio.com/latest/Data-Lifecycle.html
Doesn't contain the most important file of all. info.json (and the folder structure and naming scheme should be close by)

The event list. For some reason I always find it via the defines page. Would be nice if the defines list, for each category where applicable, could link to the actual documentation page for that category. So I wouldn't have to just read the names of the events and guess when it fires from the name and what the event table struct contains. Because I've been guessing and testing from the limited info I've found on the defines page where no onfo on what things do exists. I know now that there's an actual event list on the front page and on its own dedicated page

Impatient wrote: ↑
Fri May 10, 2019 11:20 pm
"The Lua API documentation is one of the most valuable resources for modders."

Yes, but it is not THE most valuable resource for modders.

I see only two good ways to alleviate that situation:
1. The devs do document use cases and behavior in the code. These comments are then automatically moved to the API documentation when it is generated from the code.
2. An API doc that allows for contributions by modders, where they can record their knowledge and findings and write additional articles if they want to. This can be seen eg here ( https://www.php.net/manual/en/language. ... ggling.php , scroll down to the "User contributed notes" section ) at the PHP documentation and it was so successful and high quality, that Microsoft adopted it for their shitty documentation system like a decade (later|too late to be important on the market for web development).
I disagree. The api is well structured and I get almost all my the info I need from it. But reading others code is one way to get up to speed quickly. Though you have to be careful with that though so you don't copy bad quality code into your brand new project. Also while I agree that code examples would be neat in some cases and that the few that are there are nice to have, the mod portal is already that for me and I don't think your suggestion could ever hope to match it exept for some short bits and pieces of common tricks and pitfalls. Which would still be valuable though. So I'm not against this suggestion, I'm cautiously for.
Maybe it could linked to wiki ??? ... What about making an automated link in API-doc linked to a generic lemma in wiki. So if someone like to write an article about a special LUA-object (or its methods etc.) he can do it in a related wiki article. (which should also link back to API-doc).
So a modder can search the wiki by keywords, read the article and examples and could than klick the link to API-doc.
If he then discovers an unknown reference in API-doc he just klick the wiki-link and could read what other modders had written about it.

Qon
Smart Inserter
Smart Inserter
Posts: 2091
Joined: Thu Mar 17, 2016 6:27 am
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by Qon »

TheRaph wrote: ↑
Sat May 11, 2019 8:49 am
Maybe it could linked to wiki ??? ... What about making an automated link in API-doc linked to a generic lemma in wiki. So if someone like to write an article about a special LUA-object (or its methods etc.) he can do it in a related wiki article. (which should also link back to API-doc).
So a modder can search the wiki by keywords, read the article and examples and could than klick the link to API-doc.
If he then discovers an unknown reference in API-doc he just klick the wiki-link and could read what other modders had written about it.
Sounds like a reasonable implementation that wouldn't clutter the API doc.

Herddex
Burner Inserter
Burner Inserter
Posts: 6
Joined: Thu Jul 07, 2016 5:49 pm
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by Herddex »

Please continue to work on the game after 1.0! Your updates always bring value to the game.

Grasshopper147
Manual Inserter
Manual Inserter
Posts: 1
Joined: Sat Feb 09, 2019 4:04 pm
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by Grasshopper147 »

Just a thought, but after 1.0 is released I would gladly pay again for 2.0 (and beta access into it of course). 2.0 doesnt have to be a sequel, it can simply contain new features/enemies/challenges/modes, etc.

I am a developer myself (C#, not games) and I certainly appreciate all the hard work you guys put into Factorio! It is by far my favorite piece of software and entertainment. I have gotten keys for my whole family and my daughters love it as well, and it has increased their love of STEM.

Thank you again for making this great game!

User avatar
NelsonSKA
Inserter
Inserter
Posts: 22
Joined: Fri Nov 09, 2018 7:31 pm
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by NelsonSKA »

Hi devs, I'm going to use this oportunity to congrats you for the dedication that you put in this game. I really apreciate that, and I consider that I have met one of the best developers in video games industry.

So... In reference to the FFF, it's my favourite "event" on fridays. I wait anxious until the release to read it, and not only for the news or new features, but also to LEARN about diferents topics related to the creation of video games. The way that you solve problems, and later the discussion in the forums it's very interesting for my. You really are listening to your players.

For conclude, the FFF, in my opinion, goes beyond and transcend Factorio.
I'm really happy to see this kind of connection between developers and players and I think that is very good for all us, and why not, to the industry too.

Have a nice day, sorry for my English (I'm learning).
Greetings from Argentina! :mrgreen:

metacreamy
Manual Inserter
Manual Inserter
Posts: 4
Joined: Mon Feb 06, 2017 8:36 pm
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by metacreamy »

It would be nice to have documentation in some machine readable format also.
So we could convert it into editor autocomplete/quick help db and generate lua compiling language definitions (haxe, moonscript?)

luc
Fast Inserter
Fast Inserter
Posts: 218
Joined: Sun Jul 17, 2016 9:53 pm
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by luc »

it would take users a very long time to find out that some functions, such as getting the current real time, were not available
Why is that, actually? I feel like this is one of the things requested fairly frequently, and you don't strike me as a company where management would go "but then people might make mods that help you limit your play time, can't have that!" so it must be something else. Few system resources should be exposed, but the time seems super small and innocuous to implement.

Qon
Smart Inserter
Smart Inserter
Posts: 2091
Joined: Thu Mar 17, 2016 6:27 am
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by Qon »

luc wrote: ↑
Sat May 11, 2019 10:20 pm
it would take users a very long time to find out that some functions, such as getting the current real time, were not available
Why is that, actually? I feel like this is one of the things requested fairly frequently, and you don't strike me as a company where management would go "but then people might make mods that help you limit your play time, can't have that!" so it must be something else. Few system resources should be exposed, but the time seems super small and innocuous to implement.
It would break the deterministic model. Multiplayer would definitly not work with it, at all.

Replays could technically work with it but it might be quite difficult to work in and might bloat the replay file quite a bit since the system time would have to be recorded for every single frame. Not a huge deal on modern hard drives. But It might make replays several times larger just to support this tiny almost useless feature since inputs are quite sparse data that only change a small % of the all the frames played.

And replaying from a savefile could give different results next time without any inputs which could make bug detection harderwhen people send in save files.

Wube could add a real time clock display within Factorio that wasn't available for mods though, without any problems at all. But they probably have things that they deem are higher priority on their long list.

Cadde
Fast Inserter
Fast Inserter
Posts: 149
Joined: Tue Oct 02, 2018 5:44 pm
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by Cadde »

It's great to hear you want to expand on the documentation. There are many random variables that aren't as self explanatory as they should be...
For example: https://lua-api.factorio.com/latest/Lua ... .base_area

Imagine for a second i am completely new to modding factorio and i wanted to increase flow speed through a pipe. That is, regardless of the fluid, i wanted a pipe that allowed ALL fluids to flow through it faster. Because i was running a modded game and wanted "SUPER MACHINES" that would spit out one recipe worth each tick. Which of course led to all kinds of flow related problems with pipes.

Anyways, the base_area is one such example. I had to google that one. The wiki answered my question, but it didn't really explain anything in relation to flow capacity. Flow being a completely separate mechanic to "pipe diameter" or "area" as you call it.

EDIT: Oh and it also doesn't explain the pumps 200 fluid/tick capacity (12,000 fluid/second) not actually working due to pipes only being able to handle 100 fluid/tick. Simply upping the area of the pipe did affect flow in that one case. But with underground pipes, one is still limited to the "natural flow" mechanics.

base_level was even more difficult, i had to search all the "base mod" files for instances of base_level to finally figure out what it was (which was also partly thanks to one excellent post on the forums for fluid mechanics which i had frequented) and even then it wasn't entirely clear what effects it had.
What is "height"? I have no clue!
And what is a "production type" anyways? What effects does the different options have? I get input and output, acting like a pump. And input-output is acting like mining drills and steam engines. But what other effects are there to this? What changes?

--------------------------------------

Finally, aside from the LUA API, i am begging you guys to actually document the prototypes as well.
There's so much guesswork involved with something that should be as simple as a fire.
https://wiki.factorio.com/Prototype/FireFlame

How do i change the spreading from tree to tree? More specifically, the radius the fire will spread between trees?

I know this is the wiki side of things, still doesn't change the fact that documentation for the different variables is severely lacking and it would be really nice to have some documentation of the effects of changing a variable would have.

nuhll
Filter Inserter
Filter Inserter
Posts: 922
Joined: Mon Apr 04, 2016 9:48 pm
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by nuhll »

you know what im afraid off, after each article i read?

At some point the development will stop, no weekly post, no new content... every week, since years, i wait for your newest post, and when i forget to read, im always happy when i remember and look at it.

I wonder how we could continue the ride? DLC?

User avatar
Omnifarious
Filter Inserter
Filter Inserter
Posts: 267
Joined: Wed Jul 26, 2017 3:24 pm
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by Omnifarious »

I've recommended the FFF as a developer blog to game developers and even just software developers in general. One of the great values of it is that you are as open about your mistakes as your successes.

User avatar
QGamer
Fast Inserter
Fast Inserter
Posts: 213
Joined: Fri Apr 14, 2017 9:27 pm
Contact:

Re: Friday Facts #294 - Blog thoughts & Lua documentation improvements

Post by QGamer »

Cadde wrote: ↑
Sat May 11, 2019 11:28 pm
What is "height"? I have no clue!
If I remember correctly, "height" has to do with the direction of fluid flow: if the height of a pipe is higher than the surroundings, then fluid will flow out but not in. If the height is lower than the surroundings, then fluid will flow in but not out. For example, input fluidboxes (like for chem plants) have really low height, but the output fluidboxes have a really high height.

If my explanation is incorrect or confusing, I apologize. I haven't done much work with fluids.
"Adam fell that men might be; and men are, that they might have joy."

Post Reply

Return to β€œNews”